API Reference
Checkout API
Route-backed checkout, quote, tax jurisdiction, and embed checkout handoff API reference.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
POST
/api/checkout/product
Create a Stripe checkout session or free-claim response for one product/cart request.
- Auth
- Required active developer/customer JWT and verified account email. Missing or expired sessions receive 401; unverified accounts receive 403. Guest checkout is disabled.
- Scope
- Product owner, storefront ownership, marketplace attribution, and customer identity are resolved server-side.
- Request fields
- productId or items/cartItems/lineItems
- quantity 1-100 per product
- delivery email comes from the signed-in account
- successUrl/cancelUrl optional and origin-checked
- promoCode/promo_code/coupon optional
- storefrontSlug/storefrontId optional
- marketplaceAttributed optional
- Returns
- 201 provider stripe with checkoutSessionId/url/stripeMode/saleChannel, or manual free-claim response for fully discounted/free claims.
- Side effects
- Records checkout_started analytics, stores checkout session, records abandoned checkout signal, may create free order/entitlement for free claims.
- Notes
- Server price resolution is authoritative. Subscription cart checkout supports one subscription product at a time.
POST
/api/checkout/quote
Create a server tax/checkout quote for product checkout.
- Auth
- Optional developer/customer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- product/cart body
- customer location fields where available
- Returns
- 201 quote with tax, total, jurisdiction, platform/developer allocation and expiry when internal tax checkout is enabled.
- Side effects
- Creates quote/calculation rows when internal tax engine is active.
- Notes
- When internal tax checkout is active, checkout session creation requires a valid server quote.
GET
/api/checkout/tax-jurisdictions
List checkout-supported tax jurisdictions.
- Auth
- Public read endpoint.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Returns
- countries[] supported by the internal tax jurisdiction service.
- Side effects
- None for read endpoints unless noted.
POST
/api/embed/storefront/:storeSlug/checkout
Compatibility endpoint for embedded storefront checkout attempts.
- Auth
- Allowed embed origin/domain.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- storeSlug
- cart/body context
- Returns
- 409 USE_PRODUCT_CHECKOUT_ENDPOINT and checkoutEndpoint /api/checkout/product.
- Side effects
- None for read endpoints unless noted.
- Notes
- Embedded storefront checkout is intentionally handed off to canonical product checkout.
Money source of truth
Product IDs, quantities, promo codes, and customer identity may come from the browser. Prices, discounts, tax, totals, and revenue allocation are resolved and stored server-side.