Redeem a Subscription Bot Access Token for a Member

Apply a code to a named member of your Telegram subscription bot or Discord subscription bot from your project integration.

API key scope: access-tokens:redeem (required for restricted keys).

Claim behavior and limits

user_id must be a string containing a platform user ID or a user UUID linked to exactly one identity on this project's platform. JSON numbers are rejected. An ambiguous UUID returns 409 AMBIGUOUS_PLATFORM_IDENTITY; an unlinked UUID returns 403 PLATFORM_LINK_REQUIRED.

Platform IDs are not checked remotely against Telegram or Discord. A mistyped ID consumes the code for that ID. Check the recipient before sending. This endpoint allows 60 requests per minute per acting API key and project.

Membership and Telegram access

The token's plan determines which channel or role targets the membership grants. The member makes no payment, but redemption may still count toward the project owner's usage billing based on the plan's saved value.

For a new membership, the token duration runs from redemption. For an existing same-plan membership with a future expiry, the duration is added after that expiry. Redemption cannot shorten longer existing access.

To align a new membership with an external expiry, choose an initial token duration that ends before that expiry. Then extend the selected membership using the returned membership_id. Extension only moves dates forward and cannot replace lifetime access with a finite expiry.

For Telegram, the bot delivers an access link; the member must join the channel themselves. Someone who has never started the bot may need to do so before delivery can complete. fulfillment_pending: false confirms delivery handling, not that the member has joined the channel.

Retry recovery

Recurring billing may need provider confirmation before the extension is granted. With 202, the returned dates describe existing access, not a completed new grant.

Retry the same code for the same member to recover an uncertain or pending result. A completed retry returns the original receipt with already_claimed: true. A different member receives 404. Wait for an in-flight request to finish before retrying; concurrent attempts can temporarily return 404 or 409.

For billing_pending, retry the same request or list by status to check progress. For fulfillment_pending, resolve platform access prerequisites, such as starting the Telegram bot or joining the configured Discord server, then retry the same code. Delivery can repeat after a lost acknowledgement, but retries never grant the duration twice.

If sending Idempotency-Key, retain the same key and request body for retries. Receipt recovery still uses the same code and member.

Start with Prepare Tokens for the issue-and-activate lifecycle. Use List Tokens to inspect token status after an uncertain result.