Create Checkout Session

Create a checkout session that locks product version, pricing, and currency. This is the first step in the checkout flow for both one-time and subscription products. The typical flow is:

Merchant creates a checkout session (server-side)
Returns checkoutUrl to the frontend
Customer clicks the link and lands on the hosted checkout page
Customer fills in billing details, previews tax, and completes the order

POST /v1/actions/checkout/create-session

Authentication: API Key or Store Slug

Request Body (API Key)

Field	Type	Required	Description
`productId`	string	Yes	Product ID in Short ID format (`PROD_xxx`)
`currency`	string	Yes	ISO 4217 currency code (e.g. `USD`, `EUR`, `JPY`)
`priceSnapshot`	object	No	Override pricing at session creation (API Key only, see below)
`withTrial`	boolean	No	Trial period for subscription products, three-state: `true` grants one, `false` withholds one, and omitting the field follows the product group’s own rule. Identical on a new purchase and on a plan change
`buyerEmail`	string	No	Pre-fill customer’s email on the checkout page. Ignored in plan change mode — the email comes from the origin subscription
`billingDetail`	object	No	Pre-fill billing details (see below). Ignored in plan change mode — billing details and tax come from the origin subscription
`successUrl`	string	No	Override redirect URL after successful payment. Must be an absolute `https://` URL: a relative or scheme-less value is accepted here but rejected by the payment channel when the buyer pays (`[A0003] Parameter validation failed (successRedirectUrl is invalid)`), and the buyer only sees a generic payment-failed message. After paying, the buyer lands on the cashier’s success page and is sent to this URL when they click Done — there is no automatic redirect today
`expiresInSeconds`	number	No	Session TTL in seconds (default `2700` = 45 minutes; API Key only). No maximum is enforced — keep it as short as your flow allows, because the price snapshot stays locked for the session’s whole life
`darkMode`	boolean	No	Enable dark mode for the checkout page
`metadata`	object	No	Custom key-value pairs attached to the session
`orderMerchantExternalId`	string	No	Your business-side order reference (max 128 chars).
`language`	string	No	Cashier UI language (IETF BCP 47). Must be one of the supported enum values: en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY. Sets the checkout page’s default language; the customer can switch it on the page.
`includePaymentMethods` / `excludePaymentMethods`	string[]	No	Mutually exclusive — pass at most one. include is a whitelist: offer only these (`card`, `applepay`, `googlepay`, `wechat`), and every value must be supported by the product type × currency pair. exclude is a blacklist: offer everything the currency supports except these, with values the currency does not offer silently ignored, so one blacklist can be reused across currencies. Omit both to offer every method the currency supports.
`originOrderId`	string	No	Order ID of an existing subscription in Short ID format (`ORD_xxx`). Passing it switches the endpoint into plan change mode — see Plan Change Mode
`changeTiming`	string	No	When the new plan takes effect: `immediate` or `next_period`. Omit to let the platform derive it from the change direction. Only valid together with `originOrderId`
`changeAmount`	string	No	What to actually charge for this change, as a display format string, tax inclusive (e.g. `"12.00"`). Only valid together with `originOrderId`, API Key only, and mutually exclusive with `changeCreditAmount`
`changeCreditAmount`	string	No	How much to credit against this change instead, as a display format string, tax inclusive (e.g. `"8.00"`) — same unit and tax basis as `changeAmount`. Only valid together with `originOrderId`, API Key only, and mutually exclusive with `changeAmount`

Request Body (Store Slug)

Field	Type	Required	Description
`productId`	string	Yes	Product ID in Short ID format (`PROD_xxx`)
`currency`	string	Yes	ISO 4217 currency code
`buyerEmail`	string	No	Pre-fill customer’s email
`billingDetail`	object	No	Pre-fill billing details (see below)
`successUrl`	string	No	Override redirect URL after successful payment. Must be an absolute `https://` URL: a relative or scheme-less value is accepted here but rejected by the payment channel when the buyer pays (`[A0003] Parameter validation failed (successRedirectUrl is invalid)`), and the buyer only sees a generic payment-failed message. After paying, the buyer lands on the cashier’s success page and is sent to this URL when they click Done — there is no automatic redirect today
`darkMode`	boolean	No	Enable dark mode for the checkout page
`language`	string	No	Cashier UI language (IETF BCP 47). Must be one of the supported enum values: en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY. Sets the checkout page’s default language; the customer can switch it on the page.

Store Slug authentication does not support priceSnapshot, expiresInSeconds, metadata, orderMerchantExternalId, withTrial, changeAmount, changeCreditAmount, includePaymentMethods, or excludePaymentMethods. These fields are silently ignored to prevent price tampering and session manipulation from the client side. Payment method selection is a merchant-side commercial decision (channel fees, settlement terms), so a browser cannot narrow or widen it — Store Slug sessions always offer everything the currency supports.

ID-naming convention: the same flat dual-key names (orderMerchantExternalId on checkout-side, refundTicketMerchantExternalId on refund-ticket-side) are used across request bodies, webhook payloads, and every GraphQL type that carries the value — so a value written at checkout can be read back from Order, Payment, Refund, or a webhook payload under the same field name.

There is no cancelUrl. If the buyer closes the cashier or abandons payment, nothing redirects them back to your site. The session simply expires (45 minutes by default), the order ends canceled without a charge, and no webhook fires — there is nothing for you to handle. cancelUrl, returnUrl and similar fields are silently ignored if you send them. Keep your own “back to store” link on the page that opened the cashier.

Price Snapshot Object

Field	Type	Required	Description
`amount`	string	Yes	Price as a display format string (e.g., “29.00” = $29.00)
`taxIncluded`	boolean	No	Whether the amount already includes tax (default: `false`)
`taxCategory`	string	Yes	Tax category for tax calculation (e.g., `saas`, `digital_goods`)

For one-time products, amount replaces the product’s price outright. For subscription products it replaces the regular period price only — the trial period price comes from the product version locked into the session and cannot be overridden here.

Billing Detail Object

Field	Type	Required	Description
`country`	string	Yes	ISO 3166-1 alpha-2 country code (e.g. `US`, `JP`, `DE`)
`isBusiness`	boolean	Yes	Whether this is a business purchase
`postcode`	string	No	Postal or ZIP code
`state`	string	No	State or province code (e.g. `CA`, `NY`, `ON`). Some billing countries require it
`businessName`	string	No	Legal business name. Supply it alongside `isBusiness: true` so it appears on the invoice
`taxId`	string	No	Tax registration number, e.g. an EU VAT number. Some billing countries require it

billingDetail only pre-fills the cashier. The country you send becomes the initial value of the editable country selector (a merchant value takes priority over IP-based detection), the buyer can change it, and the buyer’s final choice is what the order records. No session or URL parameter locks or hides the billing fields. Payment methods are not driven by the country: they are resolved from product type × currency plus includePaymentMethods / excludePaymentMethods; the country is used only for the tax preview and for which address fields are shown.

Plan Change Mode

Passing originOrderId switches this endpoint into plan change mode: instead of a new-purchase link, the returned checkoutUrl points at a change confirmation page for an existing subscription — the path segment after the store slug is change instead of checkout (…/store/{storeSlug}/change/{sessionId}). A plan change is two steps — this endpoint issues the link, and the customer confirms on that page. A plan change is modelled as one cancellation plus one new subscription: the old order reaches its cancelled end state and a new order runs the normal creation lifecycle. It is not an in-place edit of the existing subscription. Who can issue the link: API Key (yours, server-side) or a customer session token. Store Slug is anonymous, so it has no subscription to attribute the change to — passing originOrderId with Store Slug auth always returns 403.

Issuing the link with an SDK

Every SDK gives plan change its own method with originOrderId required, so the “only valid together with originOrderId” rejections above cannot be expressed:

import { ChangeTiming, WaffoPancake } from "@waffo/pancake-ts";

const session = await client.checkout.createPlanChangeSession({
  originOrderId: "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  productId: "PROD_3kF9mNpQrStUvWxYz1A2bC",
  currency: "USD",
  changeTiming: ChangeTiming.Immediate,
  changeCreditAmount: "8.00", // or changeAmount — never both
});
// session.checkoutUrl → https://pancake.waffo.ai/store/{slug}/change/{sessionId}

session, err := client.Checkout.CreatePlanChangeSession(ctx, pancake.CreatePlanChangeSessionParams{
    OriginOrderID:      "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    ProductID:          "PROD_3kF9mNpQrStUvWxYz1A2bC",
    Currency:           "USD",
    ChangeTiming:       pancake.Ptr(pancake.ChangeTimingImmediate),
    ChangeCreditAmount: pancake.Ptr("8.00"),
})

// Server action from createCheckoutAction()
const session = await checkout({
  type: "planChange",
  originOrderId: "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  productId: "PROD_3kF9mNpQrStUvWxYz1A2bC",
  currency: "USD",
});

These three sign with your API Key, so the pricing fields and withTrial are honored. Use checkout.authenticated.createPlanChange() (TypeScript / Next.js authenticatedPlanChange) or Checkout.Authenticated.CreatePlanChange (Go) to have the customer session token appended for you — that is the token the confirmation page needs, described next. For the customer-issued half, call customer.createPlanChangeSession() on a customer session (client.customer(token) in TypeScript, client.Customer(token) in Go, customerAction(token, "createPlanChangeSession", …) in Next.js). It runs under the customer’s own credential, so the three 403 checks above apply and the API-Key-only fields are absent from its params — the platform would drop them unannounced.

Building the link the customer opens

The returned checkoutUrl carries neither a buyer credential nor an environment flag — the session was created with your server-side credential, so the platform cannot vouch for the buyer at that point. Opening the bare URL renders the comparison page, but the confirm step fails with a missing-authorisation message. You append both parts yourself:

{checkoutUrl}?test=true#token={customerSessionToken}

Query parameter first, fragment second. Drop ?test=true in production.

Part	Rules
`#token=`	Must be the fragment, not a query parameter. The page consumes it on first paint and scrubs it from the address bar, so it never reaches server logs, referrers, or browser history — a `?token=` query parameter gets none of that, and the page does not read it
Token type	A customer token from `issue-session-token` or a buyer token. A shopper token (`request-session-token`) is rejected — it is a single-use guest credential and cannot modify an existing subscription
`buyerIdentity`	Must match the origin subscription’s buyer, or the submit is rejected as unauthorised
Token lifetime	Customer tokens live 15 minutes (sliding); the session lives 45. Mint the token right before redirecting, not when you create the session
`?test=true`	Required for test-mode sessions. The confirmation page trusts the session’s own environment once it loads, but the flag keeps the first paint and the fallback paths on the right environment

Without a token the page falls back to asking the buyer to verify their email — a working but slower path. A wrong-environment link used to fail with Environment mismatch between request and session at the confirm step.

changeAmount, changeCreditAmount and withTrial are API Key only. With any other credential they are silently ignored, the same way priceSnapshot is on a new purchase — you will not get an error telling you they were dropped.

What the origin subscription supplies

In plan change mode these values come from the subscription you are changing, not from your request body:

Value	Where it comes from
`buyerEmail`	The origin subscription. Passing it has no effect
`billingDetail`	The origin subscription. Passing it has no effect
Tax	Calculated from the origin subscription’s billing address, not from a `billingDetail` you send

The currency must also match the origin subscription — cross-currency plan changes are rejected.

Pricing the change

Two fields, two ways to price the same change. They are mutually exclusive — sending both returns 400.

Field	Means	Example
`changeAmount`	Charge this much for this period	Target plan charges `20.00`, you send `"12.00"` → the customer pays 12.00
`changeCreditAmount`	Credit this much against this period	Target plan charges `20.00`, you send `"8.00"` → the customer pays 12.00

Both are display format strings on the same unit and tax basis (tax inclusive), and both must leave a non-negative result: an amount above the target plan’s charge for this period is rejected, and so is a credit above it. The two rejections are separate messages so you can tell which field to lower. The same number means the opposite thing under each field, which is why the platform never picks one for you. Pick whichever matches how you priced the change: changeAmount when you know the final figure, changeCreditAmount when you know the discount. Either one counts as “the merchant priced this change” for the timing rules below. Internally the session stores one figure — the charge for this period — so a credit you specify is converted at issue time using the target plan’s charge at that moment.

When the new plan takes effect

changeTiming accepts immediate or next_period. Omit it and the platform derives it from the change direction, which it works out by comparing pre-tax prices: an upgrade defaults to immediate, a downgrade or same-price switch defaults to next_period.

Rule	Behavior
`immediate` window	Requires at least 24 hours before the next charge, otherwise 400
`next_period` window	Requires at least 1 hour before the current period ends, otherwise 400
Downgrade or same-price with `immediate`	Rejected unless you also price the change (`changeAmount` or `changeCreditAmount`), or send `withTrial: true`
Prorated credit	Applied on `immediate` only. `next_period` never prorates — the credit is zero

An upgrade inside the last 24 hours does not silently fall back to next period. The upgrade default is immediate, so within 24 hours of the next charge a request that omits changeTiming gets a 400 — send changeTiming: "next_period" explicitly. A downgrade already defaults to next_period, so the same window does not affect it.

One confirmed change at a time

You can issue and submit several candidate changes for the same subscription while the customer makes up their mind. The subscription is locked to one change only once a change has been confirmed by the payment channel; after that, further attempts return 409.

Response

The response body is identical to new-purchase mode — sessionId, checkoutUrl, expiresAt, and no extra fields. The change direction, the resolved timing, and the prorated credit preview are written into the session for the confirmation page to read; they are not echoed back. Two consequences:

If you omit changeTiming you will not learn which tier the platform derived. Send it explicitly when you need certainty.
The prorated credit is an estimate taken at issue time and is recalculated at submission against the days actually remaining. Do not present it to the customer as a final figure.
A next_period change confirms the card with a $0 payment record. In the Dashboard transaction list that row shows the plan price with Charged $0.00 underneath, and it is excluded from the subscription’s charge count.

For what arrives after the change lands, see subscription.plan_changed and the two plan-change events. For the customer-facing behavior of upgrades and downgrades, see Subscriptions.

Session Locks

When a checkout session is created, the following values are locked and cannot change during the session lifetime: productVersionId, productName, priceInfo, storeName, billingPeriod, withTrial, theme, buyerEmail, billingDetail In plan change mode the session additionally locks the change context: the origin subscription’s snapshot, the change direction, the resolved timing and effective moment, the prorated credit preview, and the amount you specified (a changeCreditAmount is stored as the charge it converts to). The confirmation page reads all of it from the session, so none of it can be overridden at submission — the target plan, timing, and amount are settled the moment the link is issued. Email normalization: All email fields (email, buyerEmail, contactEmail) are normalized server-side via trim().toLowerCase() before storage, cache writes, and downstream calls. Foo@Bar.COM and foo@bar.com are treated as the same account.

Example Request

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const session = await client.checkout.createSession({
  productId: "PROD_7J3K5L8M2N4P6Q9R",
  currency: "USD",
  buyerEmail: "customer@example.com",
  language: "en",
  successUrl: "https://example.com/thank-you",
});

console.log(session.sessionId);   // "cs_550e8400-e29b-41d4-a716-446655440000"
console.log(session.checkoutUrl); // "https://checkout.waffo.ai/..."
console.log(session.expiresAt);   // "2026-01-22T10:30:00.000Z"

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_2D5F8G3H1K4M6N9P" \
  -H "X-Timestamp: 1711800000" \
  -H "X-Signature: BASE64_RSA_SIGNATURE" \
  -d '{
    "productId": "PROD_7J3K5L8M2N4P6Q9R",
    "currency": "USD",
    "buyerEmail": "customer@example.com",
    "language": "en",
    "successUrl": "https://example.com/thank-you"
  }'

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: my-store-abc123" \
  -H "X-Environment: test" \
  -d '{
    "productId": "PROD_7J3K5L8M2N4P6Q9R",
    "currency": "USD"
  }'

import requests

response = requests.post(
    "https://api.waffo.ai/v1/actions/checkout/create-session",
    headers={
        "Content-Type": "application/json",
        "X-Merchant-Id": "MER_2D5F8G3H1K4M6N9P",
        "X-Timestamp": "1711800000",
        "X-Signature": "BASE64_RSA_SIGNATURE",
    },
    json={
        "productId": "PROD_7J3K5L8M2N4P6Q9R",
        "currency": "USD",
        "buyerEmail": "customer@example.com",
        "language": "en",
    },
)

data = response.json()["data"]
print(data["checkoutUrl"])

Success Response (200)

{
  "data": {
    "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "checkoutUrl": "https://checkout.waffo.ai/my-store-abc123/checkout/cs_550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-22T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`sessionId`	string	Checkout session ID (`cs_` + UUID format, not a Short ID)
`checkoutUrl`	string	Full URL to redirect the customer to the hosted checkout page
`expiresAt`	string	ISO 8601 timestamp when the session expires

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. The 409s below are exceptions in kind, not in policy: they report the subscription’s state, not a malformed body, so resubmitting the same request keeps failing until that state changes. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

Status	`errors[0].message`	What it means	Recommended handling
400	`Missing or invalid header: x-context-environment`	Environment header missing or not `test` / `prod`	Fix the header, resubmit
400	`Invalid JSON body`	Request body is not valid JSON	Fix the body, resubmit
400	`Missing required fields: productId, currency`	`productId` or `currency` is missing	Fix the body, resubmit
400	`Invalid currency format: "X". Must be 3 uppercase letters (e.g., "USD", "EUR", "JPY")`	Currency is not 3 uppercase letters (ISO 4217)	Use a valid ISO 4217 code, resubmit
400	`Invalid language, must be one of: en, pt-BR, … ms-MY`	`language` is not one of the supported cashier languages	Use a supported `language`, or omit it
400	`includePaymentMethods and excludePaymentMethods are mutually exclusive`	Both lists were provided	Pass only one of them
400	`Invalid includePaymentMethods, must be one of: card, applepay, googlepay, wechat`	A value outside the enum	Use supported values, or omit the field
400	`Currency X is not supported for onetime payments`	The currency is outside the payment method matrix (one-time: USD, EUR, GBP, HKD, JPY, CNY; subscription: USD, EUR, GBP, HKD, JPY)	Use a supported currency
400	`Payment methods not supported for X (onetime): wechat`	`includePaymentMethods` asks for a method this product type × currency does not offer	Drop the unsupported methods
400	`No payment method remains for X (onetime) after applying excludePaymentMethods`	The blacklist removed everything	Exclude fewer methods
400	`Expected format: PROD_xxx, got "..."`	`productId` Short ID could not be decoded	Fix `productId` format, resubmit
400	`orderMerchantExternalId must not be empty`	Field was provided but is empty after trim	Omit the field or pass a non-empty value
400	`orderMerchantExternalId must be at most 128 characters`	Value exceeds 128 chars	Shorten to 128 chars or less
400	`Currency X is not supported for this product`	Product has no price snapshot for the requested currency	Use a currency supported by the product
400	`originOrderId must not be empty`	Field was provided but is empty after trim	Omit the field or pass a non-empty value
400	`changeAmount must not be empty`	Field was provided but is empty after trim	Omit the field or pass a non-empty value
400	`changeCreditAmount must not be empty`	Field was provided but is empty after trim	Omit the field or pass a non-empty value
400	`Invalid changeTiming, must be one of: immediate, next_period`	A value outside the enum	Use a supported value, or omit the field
400	`changeTiming is only valid together with originOrderId`	`changeTiming` sent without `originOrderId`	Add `originOrderId`, or drop `changeTiming`
400	`changeAmount is only valid together with originOrderId`	`changeAmount` sent without `originOrderId`	Add `originOrderId`, or drop `changeAmount`
400	`changeCreditAmount is only valid together with originOrderId`	`changeCreditAmount` sent without `originOrderId`	Add `originOrderId`, or drop `changeCreditAmount`
400	`changeAmount and changeCreditAmount are mutually exclusive`	Both pricing fields were sent	Pass only one of them
400	`Expected format: ORD_xxx, got "..."`	`originOrderId` Short ID could not be decoded	Fix `originOrderId` format, resubmit
400	`Plan change is only available for subscription products`	`originOrderId` was sent with a one-time `productId`	Target a subscription product
400	`Plan change must keep the original currency X, got Y`	`currency` differs from the origin subscription’s	Resubmit with the origin subscription’s currency
400	`Target plan is the same as the current plan`	`productId` resolves to the plan the subscription is already on	Target a different plan
400	`Missing required billing fields: X`	Tax could not be calculated from the origin subscription’s billing address	Have the customer complete their billing details first
400	`Specified amount exceeds the target plan's charge for this period`	`changeAmount` is above what the target plan charges for this period	Lower `changeAmount` to at most that charge
400	`Specified credit amount exceeds the target plan's charge for this period`	`changeCreditAmount` is above what the target plan charges for this period	Lower `changeCreditAmount` to at most that charge
400	`Immediate plan change requires at least 24 hours before the next charge`	`immediate` requested — or derived for an upgrade — inside the 24-hour window	Send `changeTiming: "next_period"` explicitly
400	`Next-period plan change requires at least 1 hour before the period ends`	`next_period` requested inside the final hour of the period	Wait for the new period to start, then reissue
400	`A downgrade or same-price change cannot take effect immediately unless the merchant specifies an amount or grants a trial`	`immediate` requested for a downgrade or same-price switch with neither pricing field and no `withTrial: true`	Drop `changeTiming`, or add `changeAmount` / `changeCreditAmount` / `withTrial: true`
400	`Subscription has no current period end; plan change is unavailable until the channel reports one`	The origin subscription has no billing period recorded yet	Retry once the subscription has billed at least once
401	`Unauthorized`	Invalid API Key signature or Store Slug	Verify auth headers
403	`Store is not active`	Store status is not `active`	Activate the store first
403	`Store is not accepting payments`	In the `prod` environment, the platform has suspended payment acceptance for this store	Platform-side switch — contact Waffo support
403	`Store is not approved for production payments`	In the `prod` environment, the store has not passed production approval (`prod_enabled`, i.e. KYB review)	Use the `test` environment, or complete KYB review
403	`No payment method is currently available for this store`	Every payment method available for this currency and product type has been suspended by the platform (applies in both `test` and `prod`)	Platform-side switch — contact Waffo support
403	`Product does not belong to this store`	Product is not owned by the visiting store	Verify the product/store pair
403	`Anonymous visitors cannot change an existing subscription`	`originOrderId` was sent with Store Slug auth	Issue the link with an API Key or a customer session token
403	`Subscription order does not belong to this credential`	The origin subscription is not yours (API Key) or not the signed-in customer’s	Verify the `originOrderId` belongs to the caller
403	`Target plan is not in the same product group as the current plan`	Customer-initiated change across product groups. API Key changes are not group-restricted	Target a plan in the same group, or issue the link with an API Key
403	`Self-service plan change is not enabled for this product group`	Customer-initiated change while the group does not allow self-service changes	Enable self-service plan change on the group, or issue the link with an API Key
404	`Store not found`	No store matches the given slug	Verify slug and environment
404	`Product not found`	Product does not exist	Verify the `productId`
404	`Product not found or not active for this environment`	Product has no active version for the given environment	Activate a product version for this environment
404	`Subscription order not found`	No subscription matches `originOrderId`	Verify the `originOrderId`
409	`Only an active subscription can change plan`	The origin subscription is not `active` — pending, past due, cancelling, or already ended	Do not resubmit; a subscription in these states cannot change plan
409	`This subscription already has a confirmed plan change`	A change on this subscription has already been confirmed by the payment channel	Do not resubmit; change the new subscription once it is active
409	`A subscription in its trial period cannot change plan`	The origin subscription is still in its trial or introductory phase	Wait for the regular period to begin, then reissue
500	`Internal server error`	Unexpected server-side failure	Retry with exponential backoff (start 5s, max 3 attempts)

Payment acceptance and production approval are two independent conditions: the former is a platform-controlled switch (which can suspend the whole store or individual payment methods), the latter is the production-approval (KYB) gate. Either one alone yields a 403 in the prod environment. Neither applies in the test environment.

The default session TTL is 45 minutes (2700 seconds). When using API Key auth, you can customize this with expiresInSeconds; no upper bound is enforced. Sessions lock the product version and pricing at creation time, so price changes will not affect existing sessions.

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

Request Body (API Key)

Request Body (Store Slug)

Price Snapshot Object

Billing Detail Object

Plan Change Mode

Issuing the link with an SDK

Building the link the customer opens

What the origin subscription supplies

Pricing the change

When the new plan takes effect

One confirmed change at a time

Response

Session Locks

Example Request

Success Response (200)

Response Fields

Errors

​Request Body (API Key)

​Request Body (Store Slug)

​Price Snapshot Object

​Billing Detail Object

​Plan Change Mode

​Issuing the link with an SDK

​Building the link the customer opens

​What the origin subscription supplies

​Pricing the change

​When the new plan takes effect

​One confirmed change at a time

​Response

​Session Locks

​Example Request

​Success Response (200)

​Response Fields

​Errors

Request Body (API Key)

Request Body (Store Slug)

Price Snapshot Object

Billing Detail Object

Plan Change Mode

Issuing the link with an SDK

Building the link the customer opens

What the origin subscription supplies

Pricing the change

When the new plan takes effect

One confirmed change at a time

Response

Session Locks

Example Request

Success Response (200)

Response Fields

Errors