API reference
Checkout and Cart API
Endpoint reference for checkout session creation, tax quotes, tax jurisdictions, embedded cart display, coupon handling, and checkout handoff.
SoundSync
Checkout and embedded cart endpoints
Checkout recalculates product, promotion, subscription, and tax pricing server-side before payment.
POST
/api/checkout/product
Create a checkout session for a product or cart.
- Auth
- Required signed-in account with a verified email and active customer/developer session
- Scope
- Product or storefront scoped
- Request fields
- productId or items/cartItems/lineItems
- quantity
- customerName (delivery email comes from the signed-in account)
- successUrl
- cancelUrl
- storefrontSlug
- saleChannel
- promoCode/coupon
- marketingOptIn
- Returns
- Stripe checkout URL/session or manual free-claim result.
- Side effects
- Creates checkout session or free claim, records checkout analytics, applies promo rules, and prepares order/entitlement state after payment.
POST
/api/checkout/quote
Quote checkout tax and totals before checkout.
- Auth
- Public route with optional customer/developer token
- Scope
- Product or storefront scoped
- Request fields
- Product/cart items, customer location, checkout source, promo context.
- Returns
- Quote payload with pricing/tax details used by checkout.
GET
/api/checkout/tax-jurisdictions
List tax jurisdictions available to checkout quoting.
- Auth
- Public route
- Scope
- Product or storefront scoped
- Returns
- Country/jurisdiction list used by checkout tax UI.
POST
/api/embed/storefront/:storeSlug/cart
Accept client-side cart state for embedded storefront display.
- Auth
- Allowed embed domain
- Scope
- Product or storefront scoped
- Request fields
- items array
- Returns
- Accepted cart echo plus checkout endpoint. Checkout recalculates server-side.
POST
/api/embed/storefront/:storeSlug/cart/items
Accept one embedded cart item for display.
- Auth
- Allowed embed domain
- Scope
- Product or storefront scoped
- Request fields
- productId, quantity, item metadata
- Returns
- Accepted item echo plus checkout endpoint.
POST
/api/embed/storefront/:storeSlug/cart/coupon
Attach a coupon/promo code to embedded cart display.
- Auth
- Allowed embed domain
- Scope
- Product or storefront scoped
- Request fields
- code, coupon, or promoCode
- Returns
- Coupon echo. Final validation happens during server-side checkout.
POST
/api/embed/storefront/:storeSlug/checkout
Embedded checkout handoff route.
- Auth
- Allowed embed domain
- Scope
- Product or storefront scoped
- Returns
- 409 response pointing clients to /api/checkout/product.
- Notes
- This endpoint exists to keep embedded clients on the canonical checkout creation route.
SoundSync
Checkout payload fields
The checkout endpoint accepts single-product and cart payloads.
| Field | Use |
|---|---|
| productId | Single-product checkout. |
| items, cartItems, or lineItems | Cart checkout with product ids and quantities. |
| customerEmail/customerName | Customer identity fields when supplied before payment. |
| promoCode/coupon | Promotion code to validate during checkout. |
| storefrontSlug and saleChannel | Attribution and storefront/customer path context. |
| successUrl and cancelUrl | Customer return routes after checkout. |