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.

Gifting

Gifting is opt-in per store and off by default. The store owner enables it under Store settings > Checkout > Allow gifting. A gift object sent to a store that has not enabled it is rejected, so check with the store owner before building against it. See Gifting for what the feature does.

Including a gift object is what makes a session a gift; there is no separate boolean. Its presence routes delivery, tier upgrade pricing and per-package purchase limits to recipientUsername / recipientUuid. customer remains who pays, and who earns and spends loyalty points.

The response echoes gift back so you can reconcile which session was a gift, and carries a warnings array of non-fatal conditions your integration should know about, since there is no checkout UI to surface them to the buyer. gift is omitted entirely when the session is not a gift, and warnings is an empty array when there is nothing to report. Fields FluxStore returns as null are omitted rather than sent as null, so gift.recipientUuid is simply absent when it could not be resolved.

Common errors