API reference
Checkout and Cart API
Endpoint reference for checkout session creation, tax quotes, tax jurisdictions, embedded cart display, coupon handling, and checkout handoff.
POST /activateGET /validatePOST /deactivate
Product credentials
Activation request
Entitlement check
Device registration
Periodic validation
Deactivation when needed
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
- Public route with optional customer/developer token
- Scope
- Product or storefront scoped
- Request fields
- productId or items/cartItems/lineItems
- quantity
- customerEmail/customerName
- 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. |