Redeem Prepared Gift Code
horizon_redeem_gift_codeConsumes a saved V2 gift-code intent once and returns authoritative campaign and player state on replay, letting uncertain redemptions be retried without preparing a new sequence.
Instructions
Consumes the original persisted V2 campaign/player sequence once and returns current authoritative state on replay. Use when: an explicit consume or retry of the exact seven-field intent previously returned by horizon_prepare_gift_code and durably saved. Not for: preparing or advancing a counter after uncertainty; horizon_validate_gift_code alone does not produce an intent. Requires: userId and the player's session: sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken. Side effects: Fresh redemption and rewards commit atomically. Identical intent retries share one logical sequence slot. No automatic retry or preparation occurs. Returns: {success,campaignId,count,configRevision,alreadyApplied,replayed,giftData,grantedValues,grantedUnlocks,playerValues}. Fresh count is expectedCount+1 at the original revision. Replay has current count/state, null giftData and empty grants. Replace balances from playerValues; never add rewards locally. Remove only this exact confirmed intent; malformed replies leave it unresolved. Errors: 409 UPGRADE_REQUIRED closes V1; MIGRATION_REQUIRED needs operator migration; COUNT_AHEAD, CAMPAIGN_CHANGED, COUNTER_EXHAUSTED and STATE_CONFLICT require explicit reconciliation. Keep the original intent on every uncertain outcome, never prepare or advance automatically. V1 arguments return local UPGRADE_REQUIRED without HTTP; mixed forms return INVALID_REQUEST. A changed local host/project returns PROJECT_SCOPE_CHANGED. 401 means the session is missing or expired: sign in again and retry with the new accessToken. 403 for a session means the token belongs to another user: pass the userId that signed in. Needs HORIZON_API_KEY. Every failure returns an error result (isError) with the HTTP status and body: a 401 that horizon_test_connection also returns means HORIZON_API_KEY is wrong, 429 means the account's per-minute rate limit was reached (wait a minute, then retry).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Obsolete V1 argument, rejected with UPGRADE_REQUIRED; use the original saved intent | |
| intent | No | Required V2 recovery object: the exact seven fields durably saved from horizon_prepare_gift_code; never retarget or advance it | |
| userId | No | Obsolete V1 argument, rejected with UPGRADE_REQUIRED; the original owner is inside intent | |
| sessionToken | Yes | Current accessToken of the intent's original user, sent only as a Bearer header | |
| idempotencyId | No | Obsolete arbitrary V1 ID, never translated to a V2 sequence; rejected without HTTP |