> ## Documentation Index > Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt > Use this file to discover all available pages before exploring further. # Start a subscription > Start a subscription on a **recurring** product and run the first-cycle customer-initiated payment. Provide exactly one of `customerId` / `customerData`. `method` is one of `CARD`, `APPLE_PAY`, `GOOGLE_PAY`, `CRYPTO`. - **Card family** (`CARD` / `APPLE_PAY` / `GOOGLE_PAY`) — pass a fresh `card.tokenizedInstrument`. The first cycle is a customer-present CIT (3DS if the issuer requires SCA); the network credential is stored so Suby re-charges the renewal cycles off-session. Failed renewals are retried automatically on a progressive back-off schedule (up to 8 attempts over 30 days) — soft declines (insufficient funds, network/issuer errors, velocity limits) are retried; hard declines (stolen/lost card, closed account) end the subscription immediately. - **Crypto** (`method=CRYPTO`) — no `card`; instead pass `crypto.mode` (`qr_deposit` | `wallet_connect`), `crypto.chainId`, and `crypto.assetId`, exactly like a one-time crypto payment. The first cycle is a customer-present deposit (the response carries a deposit `instruction` rather than a card `checkout` handle). Renewals are driven by a per-cycle **renew email** (no off-session pull for crypto). ## OpenAPI ````yaml /v3-beta/api-reference/openapi.yaml post /v3/subscriptions openapi: 3.1.0 info: title: Suby.fi Merchant API version: 3.0.0-beta description: > The **v3** public merchant API for Suby.fi. RESTful (plural, resource-oriented endpoints under the `/v3` prefix). Authenticate every request with your secret API key in the `X-Suby-Api-Key` header. - `sk_live_…` keys operate in **production** (real funds). - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards, Base Sepolia crypto, no real money). The environment is derived from the key prefix. All monetary amounts are **integer cents** (except `priceCents` on some read shapes, which is a string) — token amounts are strings in the smallest unit (sats / lamports / wei). Fees are basis points. contact: email: dev@suby.fi url: https://suby.fi servers: - url: https://api.beta.suby.fi description: Production + sandbox (environment selected by API key prefix) security: - ApiKeyAuth: [] tags: - name: Products description: Manage your product catalog (one-time and recurring). - name: Checkout description: >- Hosted checkout — signed session tokens (`cs_…`) plus branding and appearance settings. - name: Payments description: >- Create, capture, void, and retrieve one-time & off-session payments (card, APM, and crypto). - name: Subscriptions description: Start and cancel recurring subscriptions. - name: Customers description: First-class customer records with billing address. - name: Payment Methods description: >- Save a payment method to a customer and manage saved instruments for off-session charges. - name: Webhook Endpoints description: Register outbound webhook destinations and rotate signing secrets. - name: Analytics description: Org-wide revenue analytics. - name: Health description: Unauthenticated liveness probe. paths: /v3/subscriptions: post: tags: - Subscriptions summary: Start a subscription description: | Start a subscription on a **recurring** product and run the first-cycle customer-initiated payment. Provide exactly one of `customerId` / `customerData`. `method` is one of `CARD`, `APPLE_PAY`, `GOOGLE_PAY`, `CRYPTO`. - **Card family** (`CARD` / `APPLE_PAY` / `GOOGLE_PAY`) — pass a fresh `card.tokenizedInstrument`. The first cycle is a customer-present CIT (3DS if the issuer requires SCA); the network credential is stored so Suby re-charges the renewal cycles off-session. Failed renewals are retried automatically on a progressive back-off schedule (up to 8 attempts over 30 days) — soft declines (insufficient funds, network/issuer errors, velocity limits) are retried; hard declines (stolen/lost card, closed account) end the subscription immediately. - **Crypto** (`method=CRYPTO`) — no `card`; instead pass `crypto.mode` (`qr_deposit` | `wallet_connect`), `crypto.chainId`, and `crypto.assetId`, exactly like a one-time crypto payment. The first cycle is a customer-present deposit (the response carries a deposit `instruction` rather than a card `checkout` handle). Renewals are driven by a per-cycle **renew email** (no off-session pull for crypto). operationId: createSubscription parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - productId - method properties: customerId: type: string example: cus_abc123 description: Mutually exclusive with customerData. customerData: $ref: '#/components/schemas/CustomerData' productId: type: string example: pro_abc123 method: type: string enum: - CARD - APPLE_PAY - GOOGLE_PAY - CRYPTO taxBehavior: type: string enum: - inclusive - exclusive description: >- MoR VAT for the recurring price (applies to every cycle). `exclusive` (default) adds VAT on top; `inclusive` treats the price as VAT-inclusive. billingAddress: $ref: '#/components/schemas/BillingAddress' businessData: $ref: '#/components/schemas/BusinessData' card: type: object description: Card options. Required for the card family; omit for CRYPTO. properties: tokenizedInstrument: type: string description: Provider-tokenized card instrument. crypto: type: object description: >- Crypto first-cycle routing. Required when method=CRYPTO; omit for the card family. properties: mode: type: string enum: - qr_deposit - wallet_connect chainId: type: integer description: Matches Chain.id (21=BTC, 101=SOL, EVM chain ids…). assetId: type: integer description: The settlement asset id. successUrl: type: string format: uri cancelUrl: type: string format: uri externalRef: type: string maxLength: 120 description: >- Your business reference (plan/order id). Stored + echoed on the subscription. Not unique. metadata: $ref: '#/components/schemas/Metadata' responses: '201': description: Subscription started content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: object properties: subscription: $ref: '#/components/schemas/Subscription' firstPayment: type: object properties: id: type: string status: type: string priceCents: type: string nullable: true currency: type: string nullable: true checkout: type: object nullable: true description: >- Card-family handoff (3DS / redirect). Mutually exclusive with `instruction`. properties: providerPaymentId: type: string threeDsChallengeUrl: type: string nullable: true redirectUrl: type: string nullable: true clientSecret: type: string nullable: true instruction: allOf: - $ref: '#/components/schemas/PaymentInstruction' nullable: true description: >- Crypto first-cycle deposit instruction (QR deposit / wallet-connect calldata). Present when method=CRYPTO. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → `422 IDEMPOTENCY_KEY_CONFLICT`; a retry while the first is still in flight → `409`. See the Idempotency guide. schema: type: string maxLength: 255 example: 5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04 schemas: CustomerData: type: object required: - email description: >- Inline customer for create-on-the-fly. Mutually exclusive with `customerId`. properties: email: type: string format: email maxLength: 320 firstName: type: string maxLength: 100 lastName: type: string maxLength: 100 BillingAddress: type: object properties: line1: type: string maxLength: 200 nullable: true line2: type: string maxLength: 200 nullable: true city: type: string maxLength: 120 nullable: true state: type: string maxLength: 120 nullable: true postalCode: type: string maxLength: 40 nullable: true country: type: string description: ISO 3166-1 alpha-2. pattern: ^[A-Z]{2}$ nullable: true BusinessData: type: object description: >- B2B purchase details. Accepted on ALL accounts — `businessName` / `taxId` are always stored on the customer, and `businessName` doubles as the card holder name. The VAT **reverse-charge** it triggers (0% VAT except France) only takes effect on Merchant-of-Record accounts; on non-MoR accounts no VAT applies at all, so it has no tax effect. properties: purchaseAsBusiness: type: boolean description: Marks the purchase as B2B (drives the MoR VAT reverse-charge). businessName: type: string maxLength: 200 nullable: true taxId: type: string maxLength: 60 nullable: true description: Buyer VAT / fiscal number. Metadata: type: object additionalProperties: type: string nullable: true description: | Key-value pairs. ≤50 keys, keys ≤40 chars, values are strings ≤500 chars (or `null` to clear). Nested structures must be JSON-stringified into a single string value. SuccessEnvelope: type: object required: - success - data properties: success: type: boolean example: true message: type: string data: description: Endpoint-specific payload. Subscription: type: object properties: id: type: string example: sub_abc123 organizationId: type: string customerId: type: string productId: type: string status: type: string enum: - INCOMPLETE - TRIALING - PENDING_3DS - PENDING_REDIRECT - ACTIVE - PAST_DUE - PAUSED - CANCELED - EXPIRED currentCycle: type: integer totalCycles: type: integer nullable: true trialEndAt: type: string format: date-time nullable: true cancelAtPeriodEnd: type: boolean currentCycleDueAt: type: string format: date-time nullable: true description: >- Period-end / access-expiry clock for BOTH rails (replaces the removed `expiresAt`): card subs renew off-session at this date, crypto subs renew by email around it. Null once no further renewal is scheduled (final cycle reached or terminated). renewalAttempt: type: integer description: >- Attempts made for the current cycle: 0 while healthy, 1..8 while dunning (card smart-retry). nextRenewalAttemptAt: type: string format: date-time nullable: true description: Scheduled next retry while PAST_DUE (card back-off). lastDeclineCategory: type: string nullable: true enum: - SOFT - HARD description: >- Category of the most recent decline: SOFT (retried) or HARD (ends the subscription). externalRef: type: string nullable: true description: Merchant business reference set at create. createdAt: type: string format: date-time updatedAt: type: string format: date-time PaymentInstruction: description: >- Crypto handoff (mutually exclusive with `checkout`), discriminated on `kind`. oneOf: - type: object properties: kind: type: string enum: - qr_deposit chainId: type: integer depositAddress: type: string expectedAmount: type: string decimals: type: integer symbol: type: string address: type: string description: Token contract / SPL mint, or `NATIVE`. bip21Uri: type: string nullable: true surchargeNote: type: string nullable: true - type: object properties: kind: type: string enum: - wallet_connect chainId: type: integer contractAddress: type: string calldata: type: string value: type: string nullable: true address: type: string blockhashExpiresAt: type: string nullable: true gasLimit: type: string nullable: true approval: type: object nullable: true properties: spender: type: string tokenAddress: type: string amount: type: string calldata: type: string Error: type: object required: - success - error properties: success: type: boolean example: false error: type: string description: Machine-readable error code. example: NOT_FOUND message: type: string example: Resource not found data: description: Optional error detail. ValidationErrorEnvelope: allOf: - $ref: '#/components/schemas/Error' - type: object properties: data: type: object properties: fieldErrors: type: array items: type: object properties: field: type: string message: type: string responses: Unauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: UNAUTHORIZED message: Invalid or missing API key NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: NOT_FOUND message: Resource not found ValidationError: description: Request failed schema validation content: application/json: schema: $ref: '#/components/schemas/ValidationErrorEnvelope' example: success: false error: VALIDATION_ERROR message: Validation failed data: fieldErrors: - field: method message: method is a required field securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Suby-Api-Key description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox). ````