Checkout
Connect Stripe, configure the paid product’s price ID and establish a customer session before creating a checkout. The default product cannot be purchased. Resolve an existing active subscription or unfinished purchase before attempting another purchase of that product.
Create and redirect
Use checkoutSessions.create to start this purchase.
// Persist this key with this logical purchase before sending the request.
const purchaseKey = crypto.randomUUID()
const checkout = await client.checkoutSessions.create({
productId: 'PAID_PRODUCT_ID',
successUrl: 'https://app.example.com/checkout/success',
cancelUrl: 'https://app.example.com/checkout/cancel',
idempotencyKey: purchaseKey
})
// Save checkoutSessionId with the purchase before leaving the page.
await saveCheckoutForCurrentCustomer(checkout.checkoutSessionId)
if (checkout.checkoutSessionURL) {
window.location.assign(checkout.checkoutSessionURL)
}saveCheckoutForCurrentCustomer is your application’s persistence function. Keep the Checkout Session ID associated with the initiating customer, not just a transient component. The returned checkout URL can be null; handle that result without sending the browser to an invalid URL.
For a retry of the same creation attempt, reuse purchaseKey and the same project, customer, product and redirect URLs. Reusing the key with different checkout inputs is rejected. If idempotencyKey is omitted, each create() call generates a new key and can start a second session. Generate a new key for a genuinely new purchase, not for a network retry.
Process the result
checkoutSessions.process verifies the saved session and returns its processing state.
Modem appends status and session_id query parameters to the checkout redirect URLs. Treat those values as navigation information, not proof of paid access. When the customer returns, load the saved session ID and verify it through Modem:
const result = await client.checkoutSessions.process(savedCheckoutSessionId)
if (result.status === 'completed') {
const current = await client.products.retrieveCurrent()
showCurrentProduct(current)
} else {
showCheckoutStatus(result.status)
}showCurrentProduct and showCheckoutStatus are application UI functions. Processing applies verified paid access; reaching your success page alone does not.
| Status | App behavior |
|---|---|
completed | Reload current product and allowance state. |
unpaid | Keep access pending; payment has not been established as paid. |
pending | Keep the session ID; checkout is still open. Recheck after the customer completes it. |
expired | Start a new checkout if the customer still wants to purchase. |
failed | Show failure and inspect the stored checkout/payment details. |
pending means the checkout is still open; unpaid means checkout completed without an established payment. Neither grants paid access. A cancellation query parameter on your return page describes navigation, not a processing status. Keep the session ID to recover or recheck the purchase.
Async payment methods may finish after redirect. Stripe webhooks also process lifecycle events. Refresh the saved checkout state rather than creating another purchase just because access has not appeared immediately.
Recover after interruption
Persist the creation key and session ID across navigation. If creation times out before you obtain the session ID, retry creation with the same key. If processing times out, keep the existing session ID and recheck that checkout’s state. Do not switch customers or projects while recovering a purchase.
Operators can inspect the project’s Stripe tab for stored Checkout Session records, lifecycle filters and processing history. It distinguishes SDK-triggered processing from webhook-triggered processing. Those records help diagnose a missing grant without charging the customer again.