> ## 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. # Create a checkout session > Mint a signed hosted-checkout token (`cs_…`). Provide a `productId`, `lineItems`, or `amount`+`currency`. `mode=subscription` requires a recurring `productId`. The returned `url` is the hosted checkout page. ## OpenAPI ````yaml /v3-beta/api-reference/openapi.yaml post /v3/checkout/sessions 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/checkout/sessions: post: tags: - Checkout summary: Create a checkout session description: | Mint a signed hosted-checkout token (`cs_…`). Provide a `productId`, `lineItems`, or `amount`+`currency`. `mode=subscription` requires a recurring `productId`. The returned `url` is the hosted checkout page. operationId: createCheckoutSession parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - mode - successUrl - cancelUrl description: > Exactly ONE pricing intent is required: `productId` (single product), `lineItems` (a bundle of products), or `amount` + `currency` (ad-hoc, no product). `mode=subscription` requires a recurring `productId` (bundles/ad-hoc are one-time only). properties: mode: type: string enum: - payment - subscription description: >- `payment` = one-shot; `subscription` = recurring (requires a recurring productId). productId: type: string example: pro_abc123 description: >- Pricing intent A: a single product. Mutually exclusive with lineItems / amount. lineItems: type: array minItems: 1 maxItems: 20 description: >- Pricing intent B: 1–20 product lines charged as one Payment (a bundle). Mutually exclusive with productId / amount. items: type: object required: - productId properties: productId: type: string example: pro_abc123 quantity: type: integer minimum: 1 maximum: 999 default: 1 adjustable: type: boolean description: >- Let the payer change the quantity within [min, max] on the hosted page. min: type: integer minimum: 0 maximum: 999 max: type: integer minimum: 1 maximum: 999 amount: type: integer minimum: 1 description: >- Pricing intent C: ad-hoc amount in cents (no product). Requires `currency`. Mutually exclusive with productId / lineItems. currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217. Required with `amount`. displayName: type: string maxLength: 200 description: >- Label on the hosted page + Payment snapshot. Ad-hoc sessions only; product-backed sessions use the product name. taxBehavior: type: string enum: - inclusive - exclusive description: >- MoR VAT: `exclusive` (default) adds VAT on top → the hosted page shows the TTC; `inclusive` treats the price as VAT-inclusive. Signed into the session. customerId: type: string example: cus_abc123 description: >- Bind the session to an existing customer. Mutually exclusive with customerData. customerData: type: object description: >- Prefill hints for the hosted page (all optional, editable by the payer). Use instead of customerId for a new buyer. Same shape as on payments, but `email` is optional here. properties: email: type: string format: email firstName: type: string maxLength: 100 lastName: type: string maxLength: 100 successUrl: type: string format: uri description: Redirect after a successful payment. Required. cancelUrl: type: string format: uri description: Redirect if the payer cancels. Required. discountCode: type: string maxLength: 40 description: Pre-apply a promo code (re-validated server-side). metadata: $ref: '#/components/schemas/Metadata' customFields: $ref: '#/components/schemas/CustomFieldArray' expiresIn: type: integer minimum: 60 maximum: 604800 description: Session TTL in seconds (default 24h, max 7d). responses: '201': description: Checkout session created content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/CheckoutSession' '401': $ref: '#/components/responses/Unauthorized' '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: 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. CustomFieldArray: type: array maxItems: 10 description: Extra fields collected on the hosted checkout page (max 10). items: $ref: '#/components/schemas/CustomField' SuccessEnvelope: type: object required: - success - data properties: success: type: boolean example: true message: type: string data: description: Endpoint-specific payload. CheckoutSession: type: object properties: id: type: string example: cs_abc123 organizationId: type: string mode: type: string enum: - payment - subscription productId: type: string nullable: true lineItems: type: array nullable: true items: type: object properties: productId: type: string quantity: type: integer adjustable: type: boolean min: type: integer max: type: integer amount: type: integer nullable: true currency: type: string nullable: true displayName: type: string nullable: true allowPromo: type: boolean customerId: type: string nullable: true customerEmail: type: string nullable: true customerFirstName: type: string nullable: true customerLastName: type: string nullable: true successUrl: type: string nullable: true cancelUrl: type: string nullable: true discountCode: type: string nullable: true metadata: type: object nullable: true additionalProperties: true customFields: type: array nullable: true items: $ref: '#/components/schemas/CustomField' status: type: string enum: - OPEN - EXPIRED - COMPLETED url: type: string description: Hosted checkout page — redirect the customer here. expiresAt: type: integer description: Epoch milliseconds. createdAt: type: integer description: Epoch milliseconds. CustomField: type: object required: - key - label - type properties: key: type: string maxLength: 50 pattern: ^[a-z0-9_]+$ description: Response-map key. label: type: string maxLength: 100 type: type: string enum: - input - select - checkbox required: type: boolean placeholder: type: string maxLength: 200 options: type: array description: Required (≥1) when `type=select`. items: type: object required: - value - label properties: value: type: string maxLength: 100 label: type: string maxLength: 100 validation: type: object description: '`type=input` only — client-side regex.' properties: regex: type: string maxLength: 500 errorMessage: type: string maxLength: 200 defaultValue: type: string maxLength: 500 description: Merchant pre-fill (editable). 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 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). ````