Checkout Sessions

Checkout sessions enable merchants to build a headless catalog on their own domain and defer the paid checkout experience to the FluxStore-hosted storefront. Your backend creates a session via the API, redirects the customer to the returned URL, and the customer returns to a configured URL after payment completes or is cancelled.

Prerequisites

Before creating checkout sessions, you must configure allowed return-URL origins in your dashboard:

1. Navigate to Dashboard > Configuration > API Keys > Checkout return URLs
2. Add the exact origin of your storefront (e.g., https://shop.example.com). Origins only, paths are not part of the match
3. Without at least one origin configured, session creation returns 400 with the message: "API checkout is not enabled for this store."

The flow

1. Your backend calls Create a checkout session with the cart items, customer info, and return URLs.
2. You redirect the customer to the url returned in the response (or render a “Continue to checkout” button).
3. The customer completes payment on the FluxStore-hosted checkout.
4. FluxStore redirects them to your successUrl or cancelUrl.

Trust webhooks for state

The successUrl is a UX hint only. Always use the order.completed webhook to confirm payment and fulfill the order. The webhook payload includes checkout_session_id so you can correlate the webhook to the original session.

The URL placeholders {CHECKOUT_SESSION_ID} and {ORDER_ID} are filled in before redirecting the customer.

Idempotency

Pass an Idempotency-Key header with your create request. If the same key is used on retry:

• Prior session is Open → returns the same session with HTTP 200 (safe to retry)
• Prior session is Completed, Cancelled, or Expired → returns HTTP 400 with the prior session’s ID and status; use a fresh key for a new session

Polling (optional)

For merchants who cannot run a webhook receiver, retrieve the session and check status. When status is Completed, orderId is populated.

Common errors