Skip to main content
POST
Create a checkout session

Authorizations

X-Suby-Api-Key
string
header
required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key
string

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.

Maximum string length: 255
Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Body

application/json

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

mode
enum<string>
required

payment = one-shot; subscription = recurring (requires a recurring productId).

Available options:
payment,
subscription
successUrl
string<uri>
required

Redirect after a successful payment. Required.

cancelUrl
string<uri>
required

Redirect if the payer cancels. Required.

productId
string

Pricing intent A: a single product. Mutually exclusive with lineItems / amount.

Example:

"pro_abc123"

lineItems
object[]

Pricing intent B: 1–20 product lines charged as one Payment (a bundle). Mutually exclusive with productId / amount.

Required array length: 1 - 20 elements
amount
integer

Pricing intent C: ad-hoc amount in cents (no product). Requires currency. Mutually exclusive with productId / lineItems.

Required range: x >= 1
currency
string

ISO 4217. Required with amount.

Pattern: ^[A-Z]{3}$
displayName
string

Label on the hosted page + Payment snapshot. Ad-hoc sessions only; product-backed sessions use the product name.

Maximum string length: 200
taxBehavior
enum<string>

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.

Available options:
inclusive,
exclusive
customerId
string

Bind the session to an existing customer. Mutually exclusive with customerData.

Example:

"cus_abc123"

customerData
object

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.

discountCode
string

Pre-apply a promo code (re-validated server-side).

Maximum string length: 40
metadata
object

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.

customFields
object[]

Extra fields collected on the hosted checkout page (max 10).

Maximum array length: 10
expiresIn
integer

Session TTL in seconds (default 24h, max 7d).

Required range: 60 <= x <= 604800

Response

Checkout session created

success
boolean
required
Example:

true

data
object
required

Endpoint-specific payload.

message
string