bulk_generate_access_codes

Queue a bulk access-code generation batch. Returns a job_id immediately — poll get_job_status for completion.

Purpose

Bulk-generate access codes for a plan. The underlying job can take minutes for large batches, so the tool returns a job_id immediately; clients poll get_job_status until status=completed. The access_code.generated event emits once per batch when the worker finishes.

Billing model: generation is free. The Stripe metered overage triggers on redemption when the creator's tier free allotment is exhausted. The response embeds a preview so callers can still surface the worst-case cost ("if all N get redeemed"). For a cost-only query, call preview_access_code_cost.

Delivery is Telegram-only. export_type must be file (CSV via bot) or messages (one Telegram message per code via bot) — both require the creator account to have a linked Telegram chat. Agents that need programmatic access must also call list_access_codes after the batch completes.

Required ability

project-access-code:create

Input schema

{
  "type": "object",
  "required": ["plan_id", "quantity", "export_type", "expiry_preset"],
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "UUID of the plan to attach the generated codes to."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "How many access codes to generate (1-1000)."
    },
    "export_type": {
      "type": "string",
      "description": "How the job delivers the codes to the creator — file (CSV via bot) or messages (one per code via bot). Required."
    },
    "expiry_preset": {
      "type": "string",
      "description": "Required. One of no_expiry, 1_day, 1_week, 1_month, 1_year, custom."
    },
    "custom_expiry_amount": {
      "type": "integer",
      "description": "When expiry_preset=custom, the amount of custom_expiry_type units. Required when preset=custom."
    },
    "custom_expiry_type": {
      "type": "string",
      "description": "When expiry_preset=custom, one of days/weeks/months/years. Required when preset=custom."
    },
    "consent": {
      "type": "boolean",
      "description": "Required and must be true when export_type=messages — acknowledges that one Telegram message per code will be sent to the creator's chat."
    }
  }
}

Output shape

{
  "data": {
    "job_id": "mjb_01HX...",
    "status": "queued",
    "enqueued_at": "2026-05-18T10:05:00Z",
    "plan_id": "pln_01HX...",
    "quantity": 50,
    "preview": {
      "free_remaining": 3,
      "chargeable_quantity": 47,
      "cost": "1.41"
    }
  }
}

Poll get_job_status with the returned job_id until status=completed or failed.

Example prompts

"Generate 10 access codes for plan pln_01HX..., deliver as CSV, no expiry."

"Generate 200 access codes for the Premium plan with a 1-year expiry, deliver as messages. I acknowledge the Telegram per-code delivery."

Failure modes

VALIDATION_FAILED — quantity out of range, unknown export_type, missing consent when export_type=messages, missing custom_expiry_amount / custom_expiry_type when expiry_preset=custom, unknown expiry_preset, or the underlying Action rejects the inputs.
RESOURCE_NOT_FOUND — unknown plan_id, or the plan belongs to a team outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-access-code:create.