Order Flow

This is the sequence the SDK runs when a customer submits the checkout form, from validation to redirect. Express checkout follows a shorter version of the same path.

Standard Submit Sequence

User submits the form
  → validate all fields
      • invalid → show errors, scroll to first error, stop
  → tokenize the card with Spreedly (credit card payments)
      • failure → emit payment:error, stop
  → build the CreateOrder payload
      • shipping address, optional billing address
      • payment token / method
      • cart items, vouchers/coupons
      • attribution (UTM, device)
  → POST the order to the API
  → emit order:completed
  → resolve the redirect URL
  → reset cart + checkout state
  → redirect the browser
  → track the purchase analytics event

The form shows a loading overlay (next-processing) during the API call.

Redirect Resolution

After the order is created, the SDK chooses where to send the customer in this priority order:

The order's payment_complete_url (used for gateway / 3-D Secure redirects)
A success URL from a meta tag
The order's order_status_url
A configured fallback

You can set the redirect URLs with meta tags in the page <head>:

<meta name="next-success-url" content="https://example.com/thank-you" />
<meta name="next-failure-url" content="https://example.com/payment-failed" />

next-next-url and os-next-page are accepted aliases for the success URL; os-failure-url for the failure URL.

If no redirect URL can be resolved, the SDK emits order:redirect-missing and leaves the cart and checkout state intact so a fallback handler can recover. The customer is not redirected.

State Reset on Success

Immediately before navigating, the SDK resets both stores:

Cart — items, vouchers, shipping method, and totals are cleared
Checkout — form data, payment token, billing address, and vouchers are cleared

Because these stores persist to sessionStorage, the cleared state is written synchronously before the page changes. The confirmation or upsell page therefore loads with an empty cart and no leftover coupons.

Reset runs only when a redirect URL is resolved. If the redirect is missing (order:redirect-missing), nothing is cleared.

Express Checkout Variant

Express wallets skip the form-field steps:

User clicks an express button
  → mark processing, set payment method, show overlay
  → validate cart is not empty
  → track add_payment_info
  → create a minimal order (cart + method, no address)
  → redirect to the wallet provider to authorize
  → on return, resolve redirect + reset state (same as above)

See Express Checkout for which buttons appear and when.

Key Events

Event	Meaning
`checkout:form-initialized`	The form finished setting up
`checkout:started`	Submit handling began
`payment:tokenized`	The card was tokenized successfully
`payment:error`	Payment / tokenization failed
`order:completed`	The order was created
`order:redirect-missing`	Order created but no redirect URL — state left intact

Full payloads are in Reference → Events.

Next Steps

Customize validation and fields: The Form
Wallet payment specifics: Express Checkout