Checkout API

The Checkout API is the server-side counterpart to the headless API. Use it from your own backend to drive end-to-end purchases — typically when you have an external storefront and want to handle payment yourself rather than redirecting to the Storra-hosted checkout page.

Auth

HTTP Basic Auth with projectId:sk_secretKey. Use a secret key from API Keys; never expose it to the browser.

curl -u "your-project-id:sk_live_xyz..." \
  https://your-store.storra.xyz/api/checkout/baskets/<ident>

Flow

1. Create a basket: POST /api/checkout/baskets with the customer's email, complete URL, and cancel URL.
2. Add items: POST /api/checkout/baskets/<ident>/items.
3. Apply a coupon or gift card if the customer entered one.
4. Initiate payment: POST /api/checkout/baskets/<ident>/initiate. Returns a redirect URL to Stripe Checkout or PayPal Express. Send the customer there.
5. Customer pays. Stripe / PayPal calls the Storra webhook. Storra creates the order and fires deliveries.
6. Customer is redirected back to your complete_url with the basket marked complete.

Why use this vs. headless

Headless API is read-mostly + customer-facing (basket CRUD). Checkout API is server-only + write-heavy (handles payment intents, captures, refunds). Use Checkout API when your backend needs to orchestrate the purchase flow itself rather than letting Storra's hosted UI handle it.