v2.checkout_sessions

Create a v2 Checkout Session

post/checkout-sessions

Request

  • Base URL: https://api.cooud.com/v2
  • URL: https://api.cooud.com/v2/checkout-sessions
  • Auth: HTTP bearer

Headers

Cooud-Compat-Datestring date required

Required per-request compat-date. Format: ISO calendar date YYYY-MM-DD. Merchants pinned to an older date have their request and response transformed by every gate whose appliesAfter is strictly greater than this date.

Idempotency-Keystring

Optional key for safely retrying POST requests. Reusing a key with the same body replays the first 2xx response; reusing it with a different body returns idempotency_key_in_use.

Cooud-Accountstring

Cooud Connect: connected account a PLATFORM key acts on behalf of, in the form cooud_acct_<26-char ULID> (the seller's store; list them with GET /accounts). Required on every store-scoped operation when the bearer is a platform key (cooud_account_required otherwise); rejected with cooud_account_not_allowed when the bearer is a store key or on platform operations such as GET /accounts. An account whose owner is not an active managed seller of the platform yields 403 account_not_connected and nothing is created. For an explicitly enabled central-receiving platform, cooud_subacct_<26-char ULID> selects an internal subaccount from GET /subaccounts. These IDs are not accepted by /accounts KYC routes. Existing cooud_acct IDs never alias central subaccount stores.

Request body

cancel_urlstring uri required
allowed_originsstring[]

Exact HTTPS origins allowed to mount Cooud Elements when ui_mode is custom. Use this when the checkout page origin differs from success_url/cancel_url. Values must be origins only, for example https://app.example.com, with no path, query, hash, credentials, wildcard, or livemode localhost. Outside ui_mode: custom it is 400 parameter_invalid, also on a Cooud LLC account.

customer_emailstring email

Buyer e-mail. Required for a Cooud LLC session with ui_mode: custom (400 parameter_missing): the Cooud LLC order is created with the session.

pricesstring[]

Catalog price IDs for native Cooud catalog checkout. Provide exactly one of prices or line_items. Use this path for Cooud-managed post-purchase offers and future native A/B/C flows. Exactly one recurring catalog price creates a subscription. Trials, application_fee_amount and post-purchase flows are refused for recurring prices. Do not send mode; it is inferred from the catalog. The session total must cover the Cooud fee of the store owner's fee plan (129 minor units of the session currency on the standard plan); below it the create is refused with 400 amount_below_minimum before any charge.

metadataobject

Optional merchant metadata copied onto the checkout session. For UTMify attribution on API-created checkouts, send utm_source, utm_medium, utm_campaign, utm_content, and utm_term here when creating the session.

presentment_amountinteger nullable
presentment_currencystring nullable
success_urlstring uri required
ui_mode'hosted' | 'custom'

Checkout presentation mode. Omit or send hosted for Cooud-hosted redirect checkout where available. Send custom to keep the buyer on your own site and confirm with /v2/checkout-sessions/{id}/confirm. On an account that sells through Cooud LLC (C-API-6, behind the Cooud LLC API gate), custom mounts the Cooud LLC Checkout Session in Cooud Elements 1.3.0 or newer (see element-config); the Cooud LLC order is created with the session, so customer_email is required, and the payment is confirmed in the browser, not through /confirm.

application_fee_amountinteger

Cooud Connect: fee the platform takes on this sale, in minor units of the session base currency (the line_items/prices currency, not the presentment currency). Accepted only when the bearer is a platform key acting on behalf of a connected account (Cooud-Account); with a store key it is parameter_unknown. Must not exceed floor(base amount × the account's application_fee_cap_bps / 10000) plus the account's application_fee_cap_fixed_amount when the base currency is its application_fee_cap_currency (the fixed part does not apply in any other currency and is never converted): a higher value is refused with 400 application_fee_exceeds_platform_limit (the message states the limit and both parts, for example "1000 bps of 10000 plus a fixed 150 BRL per sale") and is never adjusted silently. Frozen on the session; on payment the seller receives the net after the Cooud fee and this amount.

excluded_payment_method_typesstring[]

Cooud LLC accounts only (C-API-3): payment methods the hosted page must not offer (for example klarna). Wallets (apple_pay, google_pay) and the methods Cooud LLC always offers cannot be excluded (400 payment_method_not_excludable); a list that leaves nothing to offer is 400 payment_methods_empty. On a Cooud Brasil account it is an unknown field (400 parameter_unknown).

Response

Sandbox checkout session created.

amountinteger required
cancel_urlstring required
cooud_session_secretstring

Opaque Cooud session secret returned for v2 custom/own-site checkout. Send it from your backend to POST /v2/checkout-sessions/{id}/confirm; never expose a Cooud secret key in browser code.

createdinteger required
currencystring required
customer_emailstring nullable
idstring required
livemodeboolean required
metadataobject required
mode'payment' | 'subscription' required
object'checkout_session' required
request_idstring required
status'open' | 'complete' | 'expired' required

expired exists from compat-date 2027-02-01, only on a Cooud LLC hosted session that reached expires_at unpaid (before 2027-02-01 the same session says open).

success_urlstring required
urlstring uri required

Hosted checkout URL for redirect-capable sessions. Sandbox hosted redirects are served from checkout-sandbox.cooud.com. Custom own-site checkout must not redirect to this URL. For an account that sells through Cooud LLC (stripe_platform: us), the Cooud LLC product page https://checkout.cooud.com/<price ULID>?cooud_cs=<id>: the buyer pays there in the local currency (Adaptive Pricing) and comes back through Cooud to the success_url (paid or processing) or the cancel_url recorded on create. A Cooud LLC session with ui_mode: custom is paid in Cooud Elements on your page: that product page does not open it.

accountstring

Cooud Connect: present when a platform key created the session on behalf of a connected account (Cooud-Account); the account (seller store) that sells.

application_fee_amountinteger nullable

Cooud Connect: the platform fee requested on create, in minor units of the base currency. Present only on platform sessions; null when the platform did not request a fee.

subscriptionstring nullable

Stable public subscription id after successful confirmation; null before creation or when the financial record is still awaiting reconciliation. Sandbox ids are simulated and cannot be read via /subscriptions.

receiving_mode'platform_central'

Present for a centrally received company sale.

merchant_namestring

Company selling to the buyer. Display it in the checkout.

payouts_managed_by'platform'

The company handles payouts to internal users outside Cooud.

stripe_platform'us'

Cooud LLC hosted session only (C-API-3): the session sells through Cooud LLC. Absent on every other session.

payment_status'unpaid' | 'processing' | 'paid'

Cooud LLC hosted session only: paid once the order is paid, processing while an asynchronous method (OXXO, Multibanco, ACH, Pix and similar) waits for the money, unpaid otherwise. With processing, status is complete and payment.state is processing from compat-date 2027-02-01 (requires_action before it).

orderstring nullable

Cooud LLC hosted session only: the paid order of the session (the same order GET /orders?checkout_session=<id> returns); null before payment.

expires_atinteger

Cooud LLC hosted session only: Unix seconds after which an unpaid session no longer opens (24 h after creation).

Changes

No recorded changes to this operation across all 1 revision of this API.