Buy Store Bundle

This method initiates a transaction to purchase a specific bundle from your reward store. Upon successful initiation, it returns a unique transaction ID, which can be used to track the status and progress of the transaction.

Endpoint

POST /v1/store/buy

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
referenceId	string	Yes	Unique identifier for the store bundle (bundle UID)

Example Request

{
  "referenceId": "{{bundleID}}",
  "playerId": "{{playerID}}"
}

Response

Success Response

A purchase is fulfilled immediately: the provision is created, the currency is charged, the bundle contents are granted, and the transaction is returned already in the Completed state.

{
  "code": 200,
  "data": {
    "playerId": "{{playerID}}",
    "provisionUid": "3753bdcd92804b20bf93039c8c3cb44f",
    "cost": 50.00,
    "costLabel": "Coins",
    "costDeliverableUid": "41c8680620d94498b295e53e7db96045",
    "status": "Completed",
    "updateDate": 1784015804551,
    "deliverables": [
      {
        "amount": 1.00,
        "label": "Football Jersey",
        "type": 1,
        "imageName": "https://rapidmulestorage.blob.core.windows.net/images/d73830ad-d553-4871-bf3c-98839cd8c29e_jersey.png",
        "details": null
      }
    ]
  }
}

Response Fields

Field	Type	Description
playerId	string	The player who made the purchase
provisionUid	string	UID of the provision (transaction) created — use it with the Store Transactions endpoints
cost	number	Amount of currency charged
costLabel	string	Display name of the currency spent
costDeliverableUid	string	UID of the deliverable used as currency
status	string	Transaction status — a successful purchase returns Completed
updateDate	long	Unix timestamp (ms) the transaction was last updated
deliverables	array	Items granted to the player by the purchase

Error Response

{
  "code": 9001,
  "data": "Insufficient funds to commit the action"
}

Request Example

curl -X POST https://api.rapidmule.com/v1/store/buy \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "{{bundleID}}",
    "playerId": "{{playerID}}"
  }'

Use Cases

• Store Purchase Flow: Complete purchase flow with inventory checks and error handling
• Stock Validation: Check bundle stock availability before initiating purchase
• Transaction Tracking: Track purchases using transaction IDs for auditing and support

Error Codes

Code	Description	Resolution
1001	Payload is null	Check request body
1002	Invalid Player	Verify playerId exists
4001	Invalid AuthKey	Verify API key
9001	Insufficient funds to commit the action	Player doesn't have enough currency
9008	Bundle does not exist	Use valid bundleId
9009	Bundle out of stock	Check stock availability

Best Practices

1. Pre-purchase Validation: Always check player's currency and bundle availability before purchase
2. Error Handling: Implement comprehensive error handling for all failure scenarios
3. Transaction Logging: Store transaction IDs for auditing and support purposes
4. UI Feedback: Provide clear feedback to users about purchase success or failure
5. Inventory Refresh: Refresh player inventory after successful purchase

Important

This endpoint deducts currency from the player's inventory. Ensure proper validation before calling to prevent accidental purchases.

Related Endpoints

• Reward Stores - Get available stores and bundles
• Player Detail - Check player's inventory