Loading search…

Loading search…

Skip to content
CampaignsFree Items

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.

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:

Scroll horizontally if needed
CadencePeriod starts
None (one-time)Never resets. Both limits apply for the life of the campaign
DailyLocal midnight
WeeklyMonday at local midnight
MonthlyThe 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
Diagram
Diagram
100%
Scroll to explore · Zoom for detail

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

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
  • 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.

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 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.