--- title: "Free Items" description: "Learn how to let players claim Free Items without a code through the Tokenz Free Items API." source: "https://docs.tokenz.one/en/v3/free-items" api_version: "v3" locale: "en" version_status: "current" docs_stage: "prod" --- # Free Items Learn how to let players claim Free Items without a code through the Tokenz Free Items API. The Free Items API helps you run giveaways where players receive a reward without entering a code and without paying. Your server checks a campaign's status, claims on behalf of a recipient, and then handles a `redemption.completed` webhook for fulfillment. ## Overview The claim flow includes: - **Status**: Read a campaign's reward preview, remaining claims, and next reset time - **Claim**: Record a successful claim for a specific recipient and create a redemption record - **Idempotent retries**: Optional `Idempotency-Key` header replays an existing claim for the same campaign and recipient after a lost or timed-out response - **Webhook fulfillment**: Receive `redemption.completed` and grant the reward in your game backend Free Items reuse the campaign model and the `redemption.completed` webhook that Gift Codes (formerly Redemption Codes) use. The difference is that no code exists, your server supplies `campaignId` and `recipientId` instead of a Gift Code. The full request and response schemas for both endpoints are in the [Free Items API reference](https://docs.tokenz.one/en/v3/api/free-items). ## Authentication Call these endpoints from your server using a secret API key. Enable the `FreeItemStatus` scope to read status and `FreeItemClaim` to claim. Keep the key on your backend and derive `recipientId` from the authenticated player in your game. ## Recipient identifiers `recipientId` is your own identifier for the recipient: the account in your game that receives the reward. Tokenz treats it as an opaque string and does not look it up in your game, so the value you send is the only thing that identifies the recipient. Tokenz applies these rules, and nothing else: - Leading and trailing whitespace is stripped - The value cannot be blank - The value can be at most 100 characters. A longer value is rejected with `request.decoding-failed`, never silently shortened - The value is matched exactly, including letter case **Recipient identifiers are case-sensitive.** `Player_123` and `player_123` are distinct identifiers and hold separate claim allowances. Use the same stable identifier, including capitalization, on every request, from every code path that calls these endpoints. A player's own account ID from your game is usually the right choice. Whitespace trimming is the only normalization Tokenz performs. Do not lowercase or otherwise change the case of an identifier before sending it, because that would merge two distinct recipients into one. The same identifier is the same recipient everywhere. A player claiming from a different device, session or storefront is still the same recipient, and shares one allowance. ## Campaign setup and management Free Item campaigns are created and managed in the Tokenz Dashboard. If you do not see Free Item campaigns in your dashboard yet, contact Tokenz support to confirm availability for your account. Merchants use the Tokenz Dashboard to: - Create campaigns with active periods and reward configuration - Set a total claim limit and a per-recipient claim limit - Choose a refresh cadence, so both the campaign-wide and per-recipient limits reset on a schedule - Pause, resume, or end campaign operations ## Campaign statuses Free Item campaigns use the same statuses as Gift Code campaigns: - `draft`: Work in progress. Claims are rejected. All fields are editable. - `scheduled`: Published and queued. Becomes claimable at the configured `startAt` time. - `active`: Campaign is live and claims can succeed - `paused`: Manually paused. Claims are rejected. Can be resumed to `active` - `ended`: Campaign is finished. Claims are rejected. This state is irreversible An active campaign can accept claims. A scheduled campaign can also accept claims once `startAt` is reached, even before its stored status changes to `active`. Claims are rejected at or after `endAt`. Both are compared as absolute instants, so a campaign ending at midnight UTC stops accepting claims at that instant regardless of where the player is. ## Claim limits Two independent limits apply, and both are checked on every claim: - **Total claim limit**: the maximum number of claims across all recipients. For a one-time campaign, this applies for the life of the campaign; for a recurring campaign, it applies to the current period. Once reached, further claims in that period are rejected with `campaign.limit-reached`. - **Per-recipient claim limit**: how many times one recipient can claim. Once reached, that recipient is rejected with `campaign.recipient-limit-reached` for a one-time campaign, or `campaign.recipient-period-limit-reached` for a recurring campaign. Other recipients are unaffected. Per-recipient limits are enforced per `recipientId`. The same recipient claiming from a different device or session is still the same recipient. A rejected claim consumes nothing. If a recipient has already reached their own limit, the campaign's total claim count is not affected. ## Recurring campaigns A campaign can refresh both the campaign-wide and per-recipient limits on a schedule, so the campaign has a fresh allowance and the same recipient can claim again in each new period. The cadence is chosen when the campaign is created: | Cadence | Period starts | | --- | --- | | None (one-time) | Never resets. Both limits apply for the life of the campaign | | Daily | Local midnight | | Weekly | Monday at local midnight | | Monthly | The first day of the month, at local midnight | Periods are calculated in the campaign's own timezone, not the player's. Weekly periods always begin on Monday. That timezone is not returned by the API, so do not try to work out a period boundary yourself. Use `nextResetAt`, which is already the correct absolute instant, and refresh status once it passes. Both limits reset at each period boundary. For example, a daily campaign with a campaign-wide cap of 100 and a per-recipient cap of 1 allows 100 claims each day, with at most one per recipient. At the next daily reset, another 100 claims become available and each recipient can claim again. `nextResetAt` in the claim and status responses is the exact instant the current period ends and the next one begins. Use it to render a countdown. It is absent for one-time campaigns. A claim made at or after `nextResetAt` belongs to the new period, provided the campaign is still available. A reset restores both claim allowances but does not extend the campaign end time. ## Claim lifecycle 1. Your server calls `GET /v3/free-items/{campaignId}` to show the reward and the recipient's remaining claims 2. Player chooses to claim in your UI 3. Your server calls `POST /v3/free-items/claim`, sending a unique `Idempotency-Key` when you need safe retries 4. Tokenz returns a successful claim response 5. Tokenz sends a `redemption.completed` webhook 6. Your backend fulfills the reward and should use `redemptionId` to guard against duplicate fulfillment ```mermaid sequenceDiagram; autonumber; participant P as Player; participant M as Merchant Server; participant T as Tokenz API; participant W as Merchant Webhook Handler; M->>T: GET /v3/free-items/{campaignId}; T-->>M: Campaign + rewardPreview + remaining; P->>M: Claim Free Item; M->>T: POST /v3/free-items/claim; T-->>M: redemption + remainingForRecipient + nextResetAt; T->>W: webhook: redemption.completed; W->>W: Fulfill reward, using redemptionId to guard against duplicate fulfillment; ``` ## Get Free Item status Status returns the campaign preview and reward preview, plus how many claims remain. The campaign must be active, or scheduled with its start time reached, and must not have expired. Exhausted limits return `0` rather than a limit error. A status check does not reserve a claim; availability can change before the claim request. Pass `recipientId` to also receive that recipient's remaining claims for the current period. ```bash curl --request GET \ --url 'https://api.tokenz.one/v3/free-items/campaign_1p4LPTRKB5Z_t?recipientId=player_98765' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' ``` ### Request fields - `campaignId` (required, path): The Free Item campaign to read - `recipientId` (optional, query): The recipient's identifier in your system. If provided, the response includes that recipient's remaining claims. Whitespace is stripped, the value cannot be blank, it is limited to 100 characters, and it is case-sensitive. See [Recipient identifiers](https://docs.tokenz.one/en/v3/free-items#player-identifiers) ### Success response (`200`) ```json { "campaign": { "id": "campaign_1p4LPTRKB5Z_t", "name": "Weekly Free Pack" }, "rewardPreview": { "name": "Marathon Energy Gift", "imageUrl": "https://images.example.com/rewards/energy.png", "quantity": 1 }, "campaignRemaining": 842, "remainingForRecipient": 1, "nextResetAt": "2026-09-14T00:00:00Z" } ``` ### Response fields - `campaignRemaining`: Claims left across all recipients in the current period, or for the life of a one-time campaign. Absent if the campaign has no total claim limit - `remainingForRecipient`: Claims left for this recipient in the current period. Absent if `recipientId` was not provided, or the campaign has no per-recipient limit. A recipient with no claims left receives `0` rather than an error - `nextResetAt`: When both claim limits next reset. Absent for one-time campaigns ## Claim a Free Item Claim creates a redemption record for a recipient. Your backend grants the reward when it processes the webhook. A successful claim requires the campaign to be claimable and both limits to have room. ```bash curl --request POST \ --url https://api.tokenz.one/v3/free-items/claim \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Idempotency-Key: claim_player_98765_2026-09-10T08:10:00Z_a1b2c3d4' \ --data '{ "campaignId": "campaign_1p4LPTRKB5Z_t", "recipientId": "player_98765" }' ``` ### Request fields - `campaignId` (required): The Free Item campaign to claim from - `recipientId` (required): The recipient's identifier in your system. Whitespace is stripped, the value cannot be blank, it is limited to 100 characters, and it is case-sensitive. See [Recipient identifiers](https://docs.tokenz.one/en/v3/free-items#player-identifiers) - `Idempotency-Key` (optional, header): Unique identifier for this claim attempt in your system. Whitespace is stripped, the value cannot be blank, and it is limited to 256 characters. When a prior request with the same header value, `campaignId`, and `recipientId` already created a redemption, Tokenz returns `201` with that existing redemption instead of consuming another allowance. Omit to preserve legacy behavior without replay protection ### Success response (`201`) ```json { "redemption": { "redemptionId": "redemption_1p4LPTRKB5Z_t", "recipientId": "player_98765", "campaign": { "id": "campaign_1p4LPTRKB5Z_t", "name": "Weekly Free Pack" }, "reward": { "skuRedemptionReward": { "type": "EXTERNAL_SKU", "sku": "ITEM_ENERGY_GIFT", "name": "Marathon Energy Gift", "quantity": 1 } }, "redeemedAt": "2026-09-10T08:10:00Z", "kind": "FREE_ITEM_CLAIM", "source": "FREE_ITEM_CLAIM", "nextPeriodStart": "2026-09-14T00:00:00Z" }, "remainingForRecipient": 0, "nextResetAt": "2026-09-14T00:00:00Z" } ``` `remainingForRecipient` is the number of claims left after this claim, and is omitted when no per-recipient limit is configured. `nextResetAt` is omitted for one-time campaigns. The `redemption` object has no `code` field, because no code was used. `kind` is `FREE_ITEM_CLAIM`; `source` carries the same value for backward compatibility and is deprecated. `nextPeriodStart` is the next period boundary calculated from the campaign recurrence at `redeemedAt`; it is included only for recurring Free Item claims and omitted for one-time claims and Gift Code redemptions. The enclosing response’s `nextResetAt` exposes the reset time separately. See [Claim webhook](https://docs.tokenz.one/en/v3/free-items#claim-webhook). ### Idempotency and retries Send `Idempotency-Key` as an HTTP request header, not in the JSON body. Generate a fresh value for each distinct claim attempt (for example when the player clicks Claim in your UI). Reuse the same value only when retrying the **same** attempt after a network error, timeout, or lost response. If you omit `Idempotency-Key`, behavior matches earlier integrations: each successful request can create another redemption when limits allow. Do not blindly retry without a key. When the header is present, replay detection applies only when `campaignId` and `recipientId` match the original request. The same key with a different campaign or recipient is treated as a new claim. After a successful claim, deduplicate fulfillment by `redemptionId` when processing webhooks. Webhook deduplication does not prevent a second claim request without `Idempotency-Key`. ## Claim webhook After a successful claim, Tokenz sends `redemption.completed` to webhook endpoints subscribed to this event. This is the same event that Gift Codes use. **Verify the signature before you grant anything.** Every delivery carries a `Tokenz-Signature` header, and a handler that skips verification will grant Free Items to anyone who finds or guesses its URL. Verify over the raw request body, then parse. See [Secure your webhook endpoint](https://docs.tokenz.one/en/v3/checkout/webhooks-get-started#3.-secure-your-webhook-endpoint) for the steps. Treat the fields below as trustworthy only once the signature checks out. ```json { "id": "f75ff6f0-bdf9-4b25-bb96-968f8733a7e3", "object": "redemption.completed", "createdAt": "2026-09-10T08:10:00Z", "test": true, "eventData": { "type": "redemption", "version": "v3", "data": { "redemption": { "redemptionId": "redemption_1p4LPTRKB5Z_t", "campaign": { "id": "campaign_1p4LPTRKB5Z_t", "name": "Weekly Free Pack" }, "recipientId": "player_98765", "reward": { "skuRedemptionReward": { "type": "EXTERNAL_SKU", "sku": "ITEM_ENERGY_GIFT", "name": "Marathon Energy Gift", "quantity": 1 } }, "redeemedAt": "2026-09-10T08:10:00Z", "kind": "FREE_ITEM_CLAIM", "source": "FREE_ITEM_CLAIM", "nextPeriodStart": "2026-09-14T00:00:00Z" } } } } ``` ### Telling Free Item claims apart from Gift Code redemptions Free Item claims and Gift Code redemptions (formerly Redemption Codes) both arrive on `redemption.completed`. **Fulfillment usually does not need to tell them apart.** `redemptionId`, `recipientId` and `reward` are present for both, and they are everything you need to grant the reward once to the right recipient. Prefer a single fulfillment path that reads those three fields. When you do need to distinguish the two, for example for reporting: - `kind` is `FREE_ITEM_CLAIM` for a Free Item claim, and `CODE_REDEMPTION` for a Gift Code. It is set on newly emitted events; older queued payloads may omit it - `source` is deprecated and retained for backward compatibility. Existing handlers may read it, but new integrations should use `kind` - `nextPeriodStart` is included only for recurring Free Item claims. It is calculated from the campaign recurrence at `redeemedAt`, not from the webhook delivery time - `code` carries the redeemed code for a Gift Code redemption, and is **absent** for a Free Item claim. Do not assume it is present If `kind` is missing or holds a value you do not recognise, do not guess. Fulfill from `redemptionId`, `recipientId` and `reward` as usual, and flag the event for reconciliation. If you already handle `redemption.completed` for Gift Codes, review that handler before running your first Free Item campaign. A handler that reads `code` unconditionally will fail on the first claim. Use the top-level event `id` for webhook delivery tracing, and use `redemptionId` to guard against duplicate fulfillment in your backend. ### Delivery and retries If your endpoint does not accept a delivery, Tokenz retries automatically, with increasing gaps and some randomization. Retries are scheduled within a window of up to 72 hours from the first attempt. That window governs when retries are **scheduled**. It is not a promise that delivery succeeds inside it, and a scheduled attempt can still run later than planned. Do not depend on an exact number of attempts, or on exact retry times. Two consequences for your handler: - A delivery can arrive **days** after the claim. Keep your record of fulfilled `redemptionId` values in durable storage, not in a cache with a short expiry. A record that expires before the last retry will let the same reward be granted twice - The same `redemptionId` can arrive more than once. Make fulfillment idempotent on it ## Error handling Free Item endpoints return standard HTTP status codes with structured error objects. ### Common errors - `400 Bad Request` (`request.decoding-failed`): Invalid campaign id, a blank or over-length `recipientId`, a blank or over-length `Idempotency-Key`, or a malformed request - `401 Unauthorized`: Invalid or missing API key - `403 Forbidden`: API key does not have the required scope - `404 Not Found` (`entity.not-found`): Campaign not found, or it belongs to another merchant, or its mode does not match your API key - `422 Unprocessable Entity` (`campaign.kind-invalid`): The campaign is not a Free Item campaign - `422 Unprocessable Entity` (`campaign.status-invalid`): The campaign is draft, paused, ended, or scheduled before its start time - `422 Unprocessable Entity` (`campaign.expired`): The campaign has reached its end time (an ended status can instead return `campaign.status-invalid`) - `422 Unprocessable Entity` (`campaign.limit-reached`): The campaign reached its claim limit for the current period (or its lifetime limit for a one-time campaign) - `422 Unprocessable Entity` (`campaign.recipient-limit-reached`): This recipient reached the per-recipient claim limit - `422 Unprocessable Entity` (`campaign.recipient-period-limit-reached`): This recipient reached the claim limit for the current period. Retry after `nextResetAt` - `429 Too Many Requests`: Rate limit exceeded. Both endpoints are rate limited per API key and, when supplied, per recipient - `500 Server Error`: Unexpected server error ## Testing Use test mode to develop and test your Free Item integration: 1. Use test API keys (prefixed with `secret_test_`) to interact with test campaigns 2. Create test campaigns in the Tokenz Dashboard using test mode 3. Test claims are fully isolated from live data. A test API key can only claim from test campaigns, and a live API key can only claim from live campaigns 4. Test entity IDs include a `_t` suffix (e.g., `redemption_1p4LPTRKB5Z_t`) 5. Test webhooks are delivered only to your test webhook endpoints, with `"test": true` in the payload Test a successful claim and webhook, an exhausted per-recipient limit, an exhausted total limit, a period reset, paused and expired campaigns, duplicate webhook delivery, and a claim retry with the same `Idempotency-Key` that returns the same `redemptionId`. Confirm that the reward is granted once per `redemptionId`.