Buy a shop item

POST /v1/player/purchase · for player session

Use it when the player presses Buy. The coins are deducted, the purchase is made, and the item is delivered or awaits claiming, in one step. This is the only game loop request that takes an idempotency key, and the key is required. Send the player session as the bearer token. The request needs the game loop. For the three conditions (game loop enabled for the game, member consent, server membership) and the error each returns, see What has to be true first.

Body parameters

Returns

delivery contains:

spending contains:

These are the values of status:

Treat the list as open: a new value can appear.

A purchase awaiting the community's team reads status: "pending" and waitingFor: "team". An item delivered by the game's own server can read pending with waitingFor: "studio" until that server finishes the delivery: see Deliver shop items from your own platform. A delivery that fails is retried, and the member is refunded if it keeps failing: the balance then reflects the refund, and the locker shows refunded. CEEJAY does not send the member a direct message.

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/player/purchase \
  -H "Authorization: Bearer $CEEJAY_PLAYER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": 7,
    "idempotencyKey": "buy-2026-10-08-gold-skin-1",
    "expectedPrice": 500
  }'

The TypeScript example uses connect.hub.buy from the Connect client in the TypeScript SDK. The player must be connected first: the client manages and refreshes the player session. It returns the data of the response below. It generates an idempotencyKey when you pass none, and sends every attempt with the same one: see Retrying safely.

{
  "success": true,
  "data": {
    "purchaseId": 4242,
    "itemId": 7,
    "itemName": "Gold skin",
    "pricePaid": 500,
    "balance": 950,
    "status": "pending",
    "waitingFor": "studio",
    "claimNeeded": false,
    "delivery": {
      "state": "pending",
      "message": null
    },
    "duplicate": false,
    "spending": {
      "dailyCap": 5000,
      "spentToday": 500,
      "remainingToday": 4500,
      "resetsAt": "2026-10-09T00:00:00.000Z"
    }
  }
}

{
  "success": true,
  "data": {
    "purchaseId": 4242,
    "itemId": 7,
    "itemName": "Gold skin",
    "pricePaid": 500,
    "balance": 950,
    "status": "delivered",
    "waitingFor": null,
    "claimNeeded": false,
    "delivery": {
      "state": "delivered",
      "message": null
    },
    "duplicate": false,
    "spending": {
      "dailyCap": 5000,
      "spentToday": 500,
      "remainingToday": 4500,
      "resetsAt": "2026-10-09T00:00:00.000Z"
    }
  }
}

{
  "success": true,
  "data": {
    "purchaseId": 4242,
    "itemId": 7,
    "itemName": "Gold skin",
    "pricePaid": 500,
    "balance": 950,
    "status": "pending",
    "waitingFor": "studio",
    "claimNeeded": false,
    "delivery": {
      "state": "pending",
      "message": null
    },
    "duplicate": true,
    "spending": {
      "dailyCap": 5000,
      "spentToday": 500,
      "remainingToday": 4500,
      "resetsAt": "2026-10-09T00:00:00.000Z"
    }
  }
}

What a purchase needs

In addition to what every game loop request needs, a purchase spends the member's coins, so it also requires:

• The economy enabled. Otherwise 409 with the code economy_disabled.
• Proof, when the game asks for it. A device that connected without proof returns 403 with the code verified_proof_required. Reading, quests and the daily reward need none.
• The device's spending hold has ended. A new connection or a new device is held before it can spend: 409 with the code spend_on_hold, holdUntil and retryAfter. The time that counts is spending.holdUntil in Get the balance.
• Within the daily spending limit. Each player can spend a set number of coins a day through the game: beyond it, 409 with the code daily_spend_cap_reached, with cap, spentToday, price, resetsAt and retryAfter. An item priced above the limit can never be bought through the game.
• An item on the game's allow list. An item that is not on the list, is disabled or does not exist returns 404 with the code item_not_found, and the three cases cannot be distinguished.

The game loop explains each rule.

The price is exact

Send the price the player saw as expectedPrice. When the price has changed, nothing is bought and the response is 409 with the code price_changed and the current price: show the shop again. A member with an insufficient balance gets insufficient_balance with price and balance.

{
  "error": "The price of this item has changed. Read the shop again",
  "code": "price_changed",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "price": 600,
  "expectedPrice": 500
}

An item that is not on sale, that the member cannot buy, that is sold out or whose purchase limit the member has reached returns purchase_refused, with a reason and a message the game can show:

{
  "error": "This device cannot spend yet. New connections and devices cannot buy until the hold ends",
  "code": "spend_on_hold",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "holdUntil": "2026-10-09T18:06:40.000Z",
  "retryAfter": 3600
}

Retrying safely

Generate a key when the player presses Buy, store it, and retry the same request with the same key after a lost response, a 429, a 503 or a 504. Nothing is bought twice: the response is the original response with duplicate: true and the header Idempotent-Replayed: true. A game in a browser cannot read that header, so read duplicate.

When the first request never finished, because it timed out or its response was lost, a retry within the first minute returns idempotency_in_progress. After that minute the request is processed, and CEEJAY finds the first purchase by its key instead of buying again. On a 504, retry the same request with the same key. A key whose request was rejected can be reused once the cause is fixed.

A key is scoped to the member, the game and the connection: a player who moves to another player of the game, or connects again, starts a new set of keys, and another member's key is never treated as this one. Keys are retained for 30 days. Two purchases of the same item in a row need two keys.

Limits

20 writes a minute for one player session, and 60 buys and claims together an hour for one member in one game. The 20 writes are shared by Start, Verify and Answer a quest task, Buy a shop item, Claim an item and Check in. The three X-RateLimit headers report that count. Every request made with a player session also counts toward 140 a minute. See Rate limits. Over a limit the response is 429 with the code rate_limited, retryAfter and a Retry-After header. A retry served from a key counts toward neither limit.

Errors

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request of a game shares (the key, the state of the game, the origin, 405, 429, 500) are on the Errors page, and the errors specific to the game loop are under Codes of the game loop.