> ## Documentation Index > Fetch the complete documentation index at: https://docs.therius.io/llms.txt > Use this file to discover all available pages before exploring further. # Create and Activate a Subscription > Enroll a customer in a plan and charge the first billing cycle. Performs the initial CIT that registers the recurring mandate. `POST /subscription` enrolls a customer in a plan and establishes the recurring mandate that anchors every future Merchant Initiated Transaction (MIT). Enrolling a customer is a Cardholder Initiated Transaction (CIT), and a CIT may require 3D Secure. Two modes: Therius runs the initial CIT + first charge here. The customer must be present. This CIT **cannot carry out a 3D Secure challenge** — a 3DS-required card will fail. The token is a card that **already completed a CIT** (including 3DS) through `/payment/authorization` or `/payment/purchase`. No second CIT runs here. **Use this for any card that needs 3D Secure.** Supply the card as **exactly one** instrument — `nonceData`, `cardData` (PCI DSS compliant servers only), or `tokenData`. `cardOnFile` and `instalments` are ignored here — Therius owns the mandate. In record mode `networkTransactionId` / `networkReferenceId` are read from the token; pass them only for a card CIT'd outside Therius. ## Record mode Run a 3DS-capable CIT yourself, then attach the result: Call `/payment/authorization` (amount 0 = account verification) or `/payment/purchase` with `card..tokenize: true` + a `shopper.id`, and handle any 3DS challenge with the JS SDK as you would for a normal payment. The response returns a `vt_...` token. `POST /subscription` with `card.tokenData.token`. For cycle 1:
• trial or deferred `startAt` → nothing is charged;
• you charged the first cycle in your CIT (`/payment/purchase`) → also pass `firstPaymentId` (the payment `id` from that call's response); Therius marks the first invoice paid and links it, no charge;
• your CIT was a zero-value verification → omit `firstPaymentId`; Therius charges cycle 1 as an MIT against the recorded mandate (rolls the subscription back with a `402` if it declines).
The response's `firstCycle` object reports what happened. See the parameters panel above for the full field list — `planId`, `customerEmail`, and a card instrument (`nonceData`/`cardData`/`tokenData` — exactly one) are required; `customerName`/`customerDocument`, `firstPaymentId` (record mode), `startAt`, `parentSubscriptionId`/`propagateLifecycle`, and `metadata` are optional. ## Response A successful request returns `201 Created` with the full subscription object, including the subscription `id`, initial `status`, current period start and end dates, and the first invoice. ### Status on creation | Status | When it occurs | | ---------- | --------------------------------------------------------------------------- | | `active` | Plan has no trial; first charge succeeded. | | `trialing` | Plan has a `trialPeriodDays` configured. | | `past_due` | Initial CIT failed. Rare — normally a `402` is returned on decline instead. | ## Errors | Code | Meaning | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Plan not found or inactive; or (record mode) the token carries no CIT mandate, or `firstPaymentId` doesn't resolve to a settled payment that charged this token. | | `402` | Initial CIT charge declined (CIT mode), or the first-cycle MIT declined (record mode — the subscription is rolled back). | | `409` | Duplicate `Idempotency-Key` with a conflicting request body. | | `422` | Validation error — e.g. no card instrument provided, an expired/used nonce, or an invalid plan. | ```bash cURL theme={"dark"} curl -X POST https://api.therius.io/v1/subscription \ -H "Authorization: Bearer prv_production_your_key_here" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "merchantCode": "MERCHANT_001", "planId": 42, "customerEmail": "ada@example.com", "customerName": "Ada Lovelace", "card": { "nonceData": { "nonce": "" } } }' ``` ```json 201 Created theme={"dark"} {} ``` ## OpenAPI ````yaml POST /subscription openapi: 3.1.0 info: title: Therius API description: REST API for payments, subscriptions, and billing plans. version: 1.0.0 servers: - url: https://api.therius.io/v1 description: Production - url: https://api-sandbox.therius.io/v1 description: Sandbox security: - bearerAuth: [] paths: /subscription: post: tags: - Subscriptions summary: Create and activate a subscription operationId: createSubscription requestBody: required: true content: application/json: schema: type: object required: - merchantCode - planId - customerEmail - card properties: merchantCode: type: string description: Your merchant account identifier. planId: type: integer description: >- ID of an active plan. Determines amount, currency, interval and trial. customerEmail: type: string description: >- Subscriber email. Used for billing and dunning notifications. customerName: type: string description: Subscriber full name, as it should appear on invoices. customerDocument: type: string description: >- Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ). card: $ref: '#/components/schemas/SubscriptionCard' firstPaymentId: type: string description: >- Record mode only, when a first payment is due. The payment `id` from the `/payment/authorization` or `/payment/purchase` call in which you ran this card CIT - Therius verifies it charged the same vaulted token in the plan currency, then marks cycle 1 paid and links it (no charge). Omit and Therius charges cycle 1 as an MIT against the recorded mandate. startAt: type: string description: >- RFC 3339 future timestamp to defer the first charge. Omit to activate (or start the trial) immediately. parentSubscriptionId: type: string description: >- UUID of an existing subscription to attach this one to as a child (add-on hierarchies). propagateLifecycle: type: boolean description: >- When `true`, pause/cancel on `parentSubscriptionId` cascades to this subscription. Requires `parentSubscriptionId`. metadata: type: object additionalProperties: type: string description: >- Arbitrary string key/value pairs, echoed on subscription responses and webhooks. responses: '201': description: >- Subscription created. Body is the Subscription plus `firstInvoice`, and `firstCycle` in record mode (what happened to cycle 1). content: application/json: schema: $ref: '#/components/schemas/Subscription' components: schemas: SubscriptionCard: description: >- Card input for creating a subscription. Enrolling a customer is a CIT and a CIT may require 3D Secure — pick the mode that fits: • **CIT mode** (`nonceData` / `cardData`): Therius runs the initial CIT + first charge here. The customer must be present. This CIT cannot carry out a 3D Secure challenge, so a 3DS-required card will fail — use record mode for those. • **Record mode** (`tokenData`): the token is a card that already completed a CIT — including any 3DS — through `/payment/authorization` or `/payment/purchase` (with `card..tokenize: true` + `shopper.id`). No second CIT runs. The mandate is read from the token; pass `networkTransactionId` / `networkReferenceId` explicitly only for a card CIT'd outside Therius. For cycle 1: with a trial or deferred start nothing is charged; with `firstPaymentId` set Therius marks the first invoice paid and links that payment; otherwise Therius charges cycle 1 as an MIT against the recorded mandate. Provide exactly ONE of `cardData`, `nonceData`, or `tokenData`. `cardOnFile` and `instalments` are not accepted — Therius owns the mandate. allOf: - $ref: '#/components/schemas/CardInstrument' - type: object properties: networkTransactionId: type: string description: >- Record mode only. The Network Transaction ID from the original CIT. Optional when the token already carries its mandate; required when recording a card CIT'd outside Therius. networkReferenceId: type: string description: >- Record mode only. The Mastercard TLID (or scheme equivalent) from the original CIT, alongside `networkTransactionId`. Defaults to `networkTransactionId` when omitted. Subscription: type: object description: >- A customer enrollment in a plan. `plan` is embedded on single-subscription responses. Invoice/event history is not included here - use the invoice endpoints. properties: id: type: string description: Subscription UUID. merchantId: type: integer description: The merchant account that owns the subscription. planId: type: integer description: ID of the plan this subscription is enrolled in. customerEmail: type: string description: Subscriber email, used for billing and dunning notifications. customerName: type: string description: Subscriber name as it appears on invoices. customerDocument: type: string description: >- Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ). cardBrand: type: string description: Brand of the card on the mandate, e.g. `visa`. status: type: string enum: - pending - trialing - active - past_due - suspended - paused - cancelled - completed description: >- `pending` - awaiting first charge; `trialing` - in a free trial; `active` - billing normally; `past_due` - a renewal failed and dunning is running; `suspended` - dunning exhausted, needs a new CIT (`POST /subscription/{id}/payment-method` in CIT mode) to recover; `paused` - billing stopped on request, resumable; `cancelled` - terminated; `completed` - reached `maxBillingCycles`. currentPeriodStart: type: string format: date-time description: Start of the current billing period. currentPeriodEnd: type: string format: date-time description: End of the current billing period. nextBillingDate: type: string format: date-time description: When the next renewal charge is scheduled. trialStart: type: string format: date-time description: Trial start, when the plan has a trial. trialEnd: type: string format: date-time description: Trial end - the first real charge date. dunningAttemptCount: type: integer description: Failed-renewal retry attempts made in the current dunning sequence. activatedAt: type: string format: date-time description: When the subscription first became `active`. cancelledAt: type: string format: date-time pausedAt: type: string format: date-time suspendedAt: type: string format: date-time startAt: type: string format: date-time description: Deferred start, when creation set a future `startAt`. cyclesCompleted: type: integer description: Number of billing cycles charged so far. completedAt: type: string format: date-time description: When the subscription reached `maxBillingCycles`. parentSubscriptionId: type: string description: Parent subscription UUID, for add-on hierarchies. propagateLifecycle: type: boolean description: Whether pause/cancel on the parent cascades to this subscription. pendingPlanId: type: integer description: >- Plan the subscription will switch to at the next cycle, set by a `next_billing` change-plan. createdAt: type: string format: date-time updatedAt: type: string format: date-time plan: $ref: '#/components/schemas/Plan' CardInstrument: description: >- The payment instrument. Provide exactly ONE of `cardData`, `nonceData`, or `tokenData` — they are interchangeable alternatives, not fields to send together. `cardData` carries a raw PAN and requires your server to be PCI DSS compliant; `nonceData` is a single-use nonce from the Therius JS SDK; `tokenData` reuses a stored `vt_...` vault token. oneOf: - title: Raw card (PCI DSS) type: object required: - cardData properties: cardData: $ref: '#/components/schemas/CardData' - title: SDK nonce type: object required: - nonceData properties: nonceData: $ref: '#/components/schemas/NonceData' - title: Vault token type: object required: - tokenData properties: tokenData: $ref: '#/components/schemas/TokenData' Plan: type: object description: >- A reusable billing plan. `amount` is a flat integer in the currency minor units (with separate `currency` + `exponent`) - not an Amount object. properties: id: type: integer description: The plan unique integer ID. merchantId: type: integer description: The merchant account that owns the plan. name: type: string description: type: string interval: type: string enum: - day - week - month - year description: Billing interval unit. Immutable after creation. intervalCount: type: integer description: >- Number of `interval` units between charges - `month` + `3` bills quarterly. amount: type: integer description: >- Recurring charge in the currency minor units (e.g. `2999` = $29.99 at exponent 2). Immutable after creation. currency: type: string description: ISO 4217 currency code. Immutable after creation. exponent: type: integer description: >- Decimal places for `amount` / `introAmount` - `2` for USD, `0` for JPY. trialPeriodDays: type: integer description: Free-trial length in days before the first charge. `0` for no trial. introAmount: type: integer description: >- Introductory charge in minor units for the first `introBillingCycles` cycles, if set. introBillingCycles: type: integer description: >- How many initial cycles are billed at `introAmount` before the rate reverts to `amount`. maxBillingCycles: type: integer description: >- Total cycles after which the subscription auto-completes. `0` = open-ended. availableCountries: type: array items: type: string description: >- ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available everywhere. isActive: type: boolean description: >- Whether the plan accepts new subscribers. Existing subscriptions are unaffected when this is `false`. createdAt: type: string format: date-time updatedAt: type: string format: date-time CardData: type: object description: >- Raw card details. Only if your server is PCI DSS compliant to handle raw PANs — otherwise collect the card with the Therius JS SDK and send `nonceData`. properties: cardNumber: type: string description: Full PAN, digits only. example: '4111111111111111' cardholderName: type: string description: Name as it appears on the card. example: Ada Lovelace expiryMonth: type: string description: Two-digit expiry month, e.g. `12`. example: '12' expiryYear: type: string description: Four-digit expiry year, e.g. `2030`. example: '2030' cvv: type: string description: Card verification value (3 or 4 digits). example: '123' tokenize: type: boolean description: >- Set to `true` to save this card as a reusable token. Requires `shopper.id` in the request. cardAddress: $ref: '#/components/schemas/CardAddress' documentNumber: type: string description: Cardholder tax/document ID, required by some LATAM acquirers. typeOverride: type: string description: Override the detected card type, e.g. `debit`. NonceData: type: object description: >- Single-use nonce from the Therius JS SDK — no card data touches your server. Nonces are single-use and expire after a short window. properties: nonce: type: string description: The nonce string returned by the SDK. cardholderName: type: string description: Cardholder name. cardAddress: $ref: '#/components/schemas/CardAddress' tokenize: type: boolean description: >- Save the card as a token after payment. Requires `shopper.id` in the request. typeOverride: type: string description: Override the detected card type. TokenData: type: object description: A `vt_...` vault token for a card the shopper previously tokenized. properties: token: type: string description: Token ID returned from a prior tokenization. cvv: type: string description: CVV, if re-collection is required by the acquirer. cardAddress: $ref: '#/components/schemas/CardAddress' CardAddress: type: object properties: line1: type: string line2: type: string city: type: string state: type: string postalCode: type: string country: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer prv_sandbox_xxx` (sandbox). ````