Start a checkout
Requires billing:write. Puts one of your prices in front of one of your customers and answers with somewhere to send them.
What exists after this call
A subscription here, with status incomplete and an empty provider_subscription_id, and a checkout URL at the gateway. Nobody has paid. The subscription becomes real when the payer completes the checkout and the gateway tells us so — until then it is a row that exists here and nowhere else, which is why nothing about it can be changed or cancelled yet.
A checkout the payer abandons leaves that row behind, and that is deliberate: it is never deleted, because a subscription is never deleted. Several pending checkouts in one environment are several real pending checkouts.
Retrying it
Send an Idempotency-Key. A repeat under the same key answers the same subscription and the same checkout URL instead of starting a second one — which is what a lost response needs, since the first attempt’s session is already live and payable.
The price has to be sellable and chargeable
It must be recurring — a one_time price is a payment and has no subscription behind it — and it must not be archived, because withdrawing an offer is exactly the act of no longer selling it.
It must also be mapped onto the gateway: a price in your catalogue is a price here, and the gateway needs its own id for it. The mapping is per merchant account, and the account is only known after the connection’s health check has asked who the keys belong to — so an unverified connection is refused with something to go and do rather than a guess about which account collects the money.
A returning payer is not duplicated
If this customer has paid through this gateway before, the gateway’s own id for them is found and reused, so they keep one payment method and one billing history. Finding it takes a read at the gateway, and if that read cannot be made the checkout is refused rather than falling through to creating a second payer record — there is no un-merge at a gateway either.
If they have never paid, the gateway creates the payer and collects the address itself.
trial_days
Passes a free period to the gateway. The trial’s end date is not written here until the gateway says what it is: now + trial_days would be a date an entitlement expires on that nothing happens at.
Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing. Absent, the session's default organization answers.
A key you choose that makes starting a checkout safe to retry, end to end.
A repeat under the same key does not start a second checkout: it answers the same subscription and the same gateway session as the first attempt, with Idempotent-Replay: true. That is what a lost response needs — the first attempt's session is live and payable, and the answer that went missing carries the only id tying a payment to a row.
The key names one act. Sent with a different customer, price or quantity it is refused (422, idempotency_key_reused), and once the checkout it started has been paid it is refused (409, checkout_already_completed) rather than putting a second session in front of somebody who is already subscribed. Send a fresh key per checkout you mean to start: two checkouts for one customer on one price are two real checkouts, and the key is the only thing that can say otherwise.
It is forwarded to the gateway as its idempotency key too, so the retry and the original arrive there as one request. Retry with the body unchanged — the gateway compares every parameter, including success_url and cancel_url, and answers a mismatch with a refusal of its own.
255Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Body
Who is being billed. Must be a customer of this environment.
The catalogue price to sell, in this environment. Recurring, not archived, and mapped onto the gateway.
Where the payer lands after paying. Required, and it has to be an http(s) URL.
Seats or units. 1 when omitted; 0 is refused, because a line for none of something is not a line.
x >= 1Where they land if they back out. Optional — a gateway with no cancel destination returns them itself.
Free days before the first charge. Omit or 0 for none.
x >= 0Which gateway to charge through. Only needed when the environment has more than one connected: with one there is nothing to disambiguate, and with two picking for you would be choosing whose merchant account collects.
stripe Response
The subscription row and where to send the payer. expires_at is null when the gateway does not say — a made-up expiry would be a countdown to a moment nothing happens at.
What one of your customers is paying, mirrored from the gateway.
That word decides how to read every field below. The gateway is the source of truth about money; this is a local copy kept so an entitlement can be answered without a network call, joined to the rest of your data, and read while the gateway is unreachable. provider_synced_at is when the copy was last confirmed — null means never, which is what a checkout that was started and not completed looks like.