Access Codes API

Access codes are pre-generated single-use subscription activations a creator hands out.

Access codes are pre-generated single-use subscription activations a creator hands out. Internally they are pending subscription rows that a subscriber redeems; redemption just claims the row. They live under the plan they activate, at /v1/projects/{project}/plans/{plan}/access-codes.

Endpoints

GET/v1/projects/{project}/plans/{plan}/access-codesList a plan's access codes GET/v1/projects/{project}/plans/{plan}/access-codes/previewPrice a batch POST/v1/projects/{project}/plans/{plan}/access-codes/bulk-generateGenerate a batch of codes DELETE/v1/projects/{project}/plans/{plan}/access-codes/{accessCode}Revoke an access code

List a plan's access codes

GET

Pages the plan's codes, newest first, fifty per page unless you say otherwise. status narrows the list to unredeemed, redeemed or expired codes; the default all returns every state.

Raw access_code values are always masked in API responses to the last 5 characters. Plaintext codes ship only through the creator dashboard CSV export or the per-code messages a batch can be delivered as.

Requires ability

project-access-code:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_access_codes

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

plan*string

The plan, resolved within the project by the route binder.

Formatuuid

Query Parameters

limit?integer

Legacy alias of per_page, kept for clients that predate it. per_page wins when both are sent.

Range1 <= value <= 100

status?string

Which codes to list: all (the default), unredeemed, redeemed or expired. An unknown value reads as all.

Default"all"

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 15.

Range1 <= value <= 100

Default15

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

Responses

200OKapplication/json

The page.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08/access-codes?status=unredeemed"

{  "data": [    {      "id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",      "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",      "subscriber_id": null,      "code_masked": "******12345",      "expires_at": "2026-08-01T00:00:00Z",      "redeemed_at": null,      "created_at": "2026-05-18T10:05:00Z"    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: AccessCodeResource[];  links: Links;  meta: Meta;}export interface AccessCodeResource {  id: string;  plan_id: string;  subscriber_id: string | null;  code_masked: string | "";  expires_at: string | null;  redeemed_at: string | null;  created_at: string | null;}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

Price a batch

GET

Prices a batch of quantity codes without queuing it, so a caller can show the worst-case charge before generating.

curl "https://api.subscriby.net/v1/projects/$PROJECT/plans/$PLAN/access-codes/preview?quantity=50" \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

Generation is free. The metered overage is billed at redemption time, and only when your tier's free access-code allotment is already exhausted. Hand out codes freely; you only pay for the ones subscribers actually activate beyond the free quota.

The preview and the bulk-generate endpoint both return this cost breakdown so callers can surface the worst case ("if every one of these codes is redeemed, here is what you would owe").

Requires ability

project-access-code:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

preview_access_code_cost

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

plan*string

The plan, resolved within the project by the route binder.

Formatuuid

Query Parameters

quantity*integer

How many codes the batch would hold, 1 to 1,000.

Responses

200OKapplication/json

The cost preview.

data*||

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

When quantity is missing or outside 1 to 1,000; error.context.quantity says so.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08/access-codes/preview?quantity=50"

{  "data": {    "free_remaining": 3,    "chargeable_quantity": 47,    "cost": "1.41",    "exceeds_threshold": false,    "threshold": 50  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: Data | Data2 | Data3;}export interface Data {  free_remaining: unknown;  chargeable_quantity: unknown;  cost: string;  exceeds_threshold: boolean;  threshold: number | number;}export interface Data2 {  free_remaining: unknown;  chargeable_quantity: number;  cost: string;  exceeds_threshold: boolean;  threshold: number | number;}export interface Data3 {  free_remaining: number;  chargeable_quantity: number;  cost: string;  exceeds_threshold: boolean;  threshold: number;}

Generate a batch of codes

POST

Queues a batch of codes for the plan and answers 202 Accepted at once; the codes are written by a background job and delivered the way export_type names. Poll the list endpoint, or subscribe to access_code.generated, to know when the batch is ready.

curl -X POST https://api.subscriby.net/v1/projects/$PROJECT/plans/$PLAN/access-codes/bulk-generate \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{    "quantity": 50,    "export_type": "file",    "expiry_preset": "1_month"  }'

Answers 202 with the job's key, the plan, the quantity and the cost preview the pricing endpoint describes. Bulk generation is limited to 10 batches per minute per token in its own bucket, on top of the token's general limits; the eleventh answers 429 RATE_LIMITED with Retry-After.

The validation rules are identical to the creator dashboard's: quantity 1 to 1,000; export_type file or messages, with consent: true required for messages because one bot message per code can trip the connector's rate limits; expiry_preset one of no_expiry, 1_day, 1_week, 1_month, 1_year or custom, the last needing custom_expiry_amount and custom_expiry_type (days, weeks, months or years).

Requires ability

project-access-code:create

The token must hold this ability, or the call is refused with 403.

Fires one event

access_code.generated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

bulk_generate_access_codes

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

plan*string

The plan, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

A batch of access codes to generate: how many, how they are delivered to you, and when they expire.

quantity*integer

How many codes to generate, 1 to 1,000 per batch.

Range1 <= value <= 1000

export_type*AccessCodeExportType

How the plaintext codes reach you: file for one downloadable file, messages for one message per code to your connected account. There is no silent mode; to read the codes programmatically, list them once the batch has finished.


`file` One CSV with every code, for spreadsheets and automation.
`messages` One forwardable message per code, capped so a batch cannot flood the chat.

Value in

"file"
"messages"

consent?unknown

Must be true when export_type is messages: one message per code is high volume and can trip the connector's rate limits, so you acknowledge it explicitly. Ignored otherwise.

Value in

"yes"
"on"
"1"
1
"true"
true

expiry_preset*AccessCodeExpiryPreset

When unredeemed codes stop working: no_expiry, 1_day, 1_week, 1_month, 1_year, or custom with an amount and a unit.


`no_expiry` The code stays redeemable until it is used or revoked.
`1_day`
`1_week`
`1_month`
`1_year`
`custom` An amount of a unit, supplied alongside the preset.

Value in

"no_expiry"
"1_day"
"1_week"
"1_month"
"1_year"
"custom"

custom_expiry_amount?|

How many units the codes live for; required when expiry_preset is custom, at least 1.

Range1 <= value

custom_expiry_type?|

The unit of custom_expiry_amount: days, weeks, months or years. Required when expiry_preset is custom. No minutes or hours: a code that dies within the hour it was generated is a support ticket, not a feature.

Responses

202Acceptedapplication/json

202 with the job key, the plan, the quantity and the preview.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when a rule above is broken; error.fields names the key, and the consent and custom-expiry messages spell out what was missing.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted. On this endpoint: RATE_LIMITED: when the token has queued 10 batches within a minute.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08/access-codes/bulk-generate" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "quantity": 1,    "export_type": "file",    "expiry_preset": "no_expiry"  }'

{  "data": {    "unique_key": "user_plan_key",    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",    "quantity": 50,    "status": "generation_queued",    "preview": {      "free_remaining": 3,      "chargeable_quantity": 47,      "cost": "1.41",      "exceeds_threshold": false,      "threshold": 50    }  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface BulkGenerateAccessCodesRequest {  quantity: number;  export_type: "file" | "messages";  consent?: unknown;  expiry_preset: "no_expiry" | "1_day" | "1_week" | "1_month" | "1_year" | "custom";  custom_expiry_amount?: number | null;  custom_expiry_type?: "days" | "weeks" | "months" | "years" | null;}

Response

export interface Response {  data: Data;}export interface Data {  unique_key: string;  plan_id: string;  quantity: number;  status: string;  preview: Preview | Preview2 | Preview3;}export interface Preview {  free_remaining: unknown;  chargeable_quantity: unknown;  cost: string;  exceeds_threshold: boolean;  threshold: number | number;}export interface Preview2 {  free_remaining: unknown;  chargeable_quantity: number;  cost: string;  exceeds_threshold: boolean;  threshold: number | number;}export interface Preview3 {  free_remaining: number;  chargeable_quantity: number;  cost: string;  exceeds_threshold: boolean;  threshold: number;}

Revoke an access code

DELETE

Deletes an unredeemed code so it can no longer be claimed. The code is resolved within the plan, so an id from another plan is 404 RESOURCE_NOT_FOUND. Answers 204 with no body; no webhook fires.

Requires ability

project-access-code:delete

The token must hold this ability, or the call is refused with 403.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

plan*string

The plan, resolved within the project by the route binder.

Formatuuid

accessCode*string

The unredeemed code, resolved within the plan by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08/access-codes/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Generate Access CodesCreate redeemable access codes for free memberships, offline sales, giveaways, team access, or influencer campaigns.access_code.* eventsgenerated once per batch when the job completes, never per code; redeemed per code as subscribers claim them; expired per code when the reaper removes an unredeemed code past its expiry.Plans APIThe plan a code activates.

Access Codes API

EndpointsCopy Anchor Link

List a plan's access codesCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Price a batchCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Generate a batch of codesCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Revoke an access codeCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List a plan's access codes

Authorization

Path Parameters

Query Parameters

Responses

Price a batch

Authorization

Path Parameters

Query Parameters

Responses

Generate a batch of codes

Authorization

Path Parameters

Header Parameters

Request body

Responses

Revoke an access code

Authorization

Path Parameters

Header Parameters

Responses