Access Codes

Generate a batch of codes

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

post/v1/projects/{project}/plans/{plan}/access-codes/bulk-generate

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/projects/{project}/plans/{plan}/access-codes/bulk-generate
  • Auth: HTTP bearer

Path parameters

projectstring uuid required

The project, resolved by the route binder.

planstring uuid required

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

Headers

Idempotency-Keystring uuid required

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.

Request body

quantityinteger required

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

export_type'file' | 'messages' required

How a generated batch of access codes is handed to the creator. Both routes go through the creator's chat with the platform bot, because the batch is generated on a queue after the request returned and the bot is the one channel every creator already has open.

file <br/> One CSV with every code, for spreadsheets and automation.
messages <br/> One forwardable message per code, capped so a batch cannot flood the chat.
consentunknown
expiry_preset'no_expiry' | '1_day' | '1_week' | '1_month' | '1_year' | 'custom' required

When a generated access code stops being redeemable. The presets cover what creators pick nearly every time; Custom takes an amount and a unit for the rest. The instant is resolved when the batch is generated, so every code in a batch shares one expiry.

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

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

custom_expiry_type'days' | 'weeks' | 'months' | 'years'

The unit of a custom access-code expiry. Deliberately no minutes or hours: a code that dies within the hour it was generated is a support ticket, not a feature.

Response

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

Example response

{
  "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",
      "threshold": 50
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.