Claim an item

POST /v1/player/claim · for player session

Use it when the player claims a purchase from Read the locker whose status is claimable. The item is delivered or passed to the community's team for fulfilment, the role is assigned, or the giveaway is entered. A purchase that was already claimed returns alreadyClaimed: true with its current status, which is also what a retry after a lost response returns, so the request is safe to repeat and takes no key. 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:

status and waitingFor have the values of Buy a shop item.

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/player/claim \
  -H "Authorization: Bearer $CEEJAY_PLAYER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseId": 4242,
    "input": {
      "title": "Harbour RFC"
    }
  }'

The TypeScript example uses connect.hub.claim 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.

{
  "success": true,
  "data": {
    "purchaseId": 4242,
    "claimed": true,
    "alreadyClaimed": false,
    "itemName": "Gold skin",
    "status": "pending",
    "waitingFor": "delivery",
    "delivery": {
      "state": "pending",
      "message": null
    }
  }
}

{
  "success": true,
  "data": {
    "purchaseId": 4242,
    "claimed": true,
    "alreadyClaimed": true,
    "itemName": "Gold skin",
    "status": "pending",
    "waitingFor": "delivery",
    "delivery": {
      "state": "pending",
      "message": null
    }
  }
}

What a claim needs

A claim redeems what a purchase bought, so it has the same requirements as buying: a device that connected with proof when the game requires proof (403 with the code verified_proof_required), and a connection and a device whose spending hold has ended (409 with the code spend_on_hold). It spends no coins and does not count toward the daily limit. The game loop explains the rules.

Only the member's own purchases, made through this game or of an item on the game's allow list, can be claimed here. Any other purchase, a purchase of another member or of another community, and an earned reward all return 404 with the code purchase_not_found. A purchase that is not claimable and not already claimed returns 409 with the code not_claimable and its status. When the item requires input and input is missing or invalid, the response is 400 with field: "input", and fields lists the inputs required.

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.

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.