api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

BodyJSON

Mock

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

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 through an authorized admin or project integration.

POST/v2/projects/{project_id}/access-tokens/redeem

Authorization

Bearer TokenRequired

Requires memberships:add for a human admin. Restricted project API keys need access-tokens:redeem; access-tokens:create alone is insufficient.

Path Parameters

project_idstringrequired

The UUID of the project.

Headers

Idempotency-Keystring

Use a unique key for each distinct action; retain it with the unchanged request body when retrying.

Request Body

codestringrequired

The access code issued for this project.

user_idstringrequired

Platform user ID as a string, or a user UUID linked to exactly one identity on this project's platform. JSON numbers are rejected.

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 admin or key and project.

Response fields

Field	Meaning
`access_token_id`, `membership_id`	Identifiers for the token and resulting membership.
`membership_start_date`, `membership_end_date`	Unix milliseconds; end date is `null` for lifetime access.
`already_claimed`	This code already granted access to this member. No second extension occurred.
`fulfillment_pending`	Platform access delivery is pending. A membership is not itself a channel join.
`billing_pending`	When true, billing must settle before additional access is granted; response status is `202`.

Existing access to the same plan is extended according to its membership rules. 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.

For a signed-in member redeeming their own code, use Claim Token. See the Access Tokens overview for the issue-and-activate lifecycle.

curl -X POST "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" \
  -d '{
  "code": "YOUR_ACCESS_CODE",
  "user_id": "123456789012345678"
}'

const response = await fetch("https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem", {
  method: 'POST',
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "YOUR_UNIQUE_REQUEST_KEY"
  },
  body: JSON.stringify({
    "code": "YOUR_ACCESS_CODE",
    "user_id": "123456789012345678"
  })
});
const result = await response.json();

import requests
 
response = requests.post(
    "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        "Idempotency-Key": "YOUR_UNIQUE_REQUEST_KEY"
    },
    json={
        "code": "YOUR_ACCESS_CODE",
        "user_id": "123456789012345678"
    }
)
result = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_TOKEN',
    'Content-Type: application/json',
    'Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'code' => 'YOUR_ACCESS_CODE',
    'user_id' => '123456789012345678'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Access granted or original receipt replayedapplication/json

{
  "ok": true,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem",
  "code": 200,
  "message": "Success",
  "data": {
    "access_token_id": "11111111-1111-4111-8111-111111111111",
    "membership_id": "33333333-3333-4333-8333-333333333333",
    "membership_start_date": 1792430400000,
    "membership_end_date": 1795108800000,
    "already_claimed": false,
    "fulfillment_pending": false,
    "billing_pending": false
  }
}

Billing confirmation pendingapplication/json

{
  "ok": true,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/access-tokens/redeem",
  "code": 202,
  "message": "Success",
  "data": {
    "access_token_id": "11111111-1111-4111-8111-111111111111",
    "membership_id": "33333333-3333-4333-8333-333333333333",
    "membership_start_date": 1792430400000,
    "membership_end_date": 1795108800000,
    "already_claimed": false,
    "fulfillment_pending": true,
    "billing_pending": true
  }
}

Last updated: October 19, 2026