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.
/api/checkout/product
Create a checkout session for a product or cart.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- productId: integer
- quantity: integer
- items: array
- promoCode: string
- taxQuoteId: string
- quoteId: string
- locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.
- headlessOrigin: string
- storefrontSlug: string
- paymentProvider: stripe | paypal
- marketingOptIn: boolean
- marketingOptOut: boolean
- offerId: string
- offerVersionId: string
- priceVersionId: string
- Returns
- Stripe Checkout URL/session, PayPal approval URL for one-time purchases, 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.
- Notes
- Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"offerId": {
"type": "string",
"format": "uuid"
},
"offerVersionId": {
"type": "string",
"format": "uuid"
},
"priceVersionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true,
"required": [
"productId"
]
},
"maxItems": 100
},
"promoCode": {
"type": "string"
},
"taxQuoteId": {
"type": "string"
},
"quoteId": {
"type": "string"
},
"locationEvidenceToken": {
"type": "string",
"maxLength": 2048,
"description": "Short-lived browser-edge location proof, not a customer token."
},
"headlessOrigin": {
"type": "string",
"format": "uri"
},
"storefrontSlug": {
"type": "string"
},
"paymentProvider": {
"enum": [
"stripe",
"paypal"
]
},
"marketingOptIn": {
"type": "boolean"
},
"marketingOptOut": {
"type": "boolean"
},
"offerId": {
"type": "string",
"format": "uuid"
},
"offerVersionId": {
"type": "string",
"format": "uuid"
},
"priceVersionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true,
"anyOf": [
{
"required": [
"productId"
]
},
{
"required": [
"items"
]
}
]
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"provider": {
"enum": [
"stripe",
"paypal",
"manual"
]
},
"checkoutSessionId": {
"type": "string"
},
"url": {
"type": "string"
},
"orderId": {
"type": "integer",
"minimum": 1
},
"paypalMode": {
"type": "string"
},
"stripeMode": {
"type": "string"
},
"freeClaim": {
"type": "boolean"
},
"alreadyClaimed": {
"type": "boolean"
},
"claimed": {
"type": "boolean"
},
"checkoutBypassed": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 503.
Operation errors: CHOOSE_OFFER_REQUIRED, OFFER_CHANGED, CHECKOUT_OFFER_REQUIRED, CHECKOUT_OFFER_VERSION_CONFLICT, SUBSCRIPTION_CART_UNSUPPORTED.
/api/checkout/quote
Quote checkout tax and totals before checkout.
- Auth
- Optional authentication OR Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- productId: integer
- items: array
- countryCode: string
- regionCode: string
- postalCode: string
- promoCode: string
- headlessOrigin: string
- storefrontSlug: string
- locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.
- offerId: string
- offerVersionId: string
- priceVersionId: string
- quoteId: string
- Returns
- Quote payload with pricing/tax details used by checkout.
- Notes
- Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"offerId": {
"type": "string",
"format": "uuid"
},
"offerVersionId": {
"type": "string",
"format": "uuid"
},
"priceVersionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true,
"required": [
"productId"
]
},
"maxItems": 100
},
"countryCode": {
"type": "string"
},
"regionCode": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"promoCode": {
"type": "string"
},
"headlessOrigin": {
"type": "string",
"format": "uri"
},
"storefrontSlug": {
"type": "string"
},
"locationEvidenceToken": {
"type": "string",
"maxLength": 2048,
"description": "Short-lived browser-edge location proof, not a customer token."
},
"offerId": {
"type": "string",
"format": "uuid"
},
"offerVersionId": {
"type": "string",
"format": "uuid"
},
"priceVersionId": {
"type": "string",
"format": "uuid"
},
"quoteId": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"quote": {
"type": "object",
"properties": {
"quoteId": {
"type": "string"
},
"currency": {
"type": "string"
},
"subtotalCents": {
"type": "integer",
"minimum": 0
},
"taxAmountCents": {
"type": "integer",
"minimum": 0
},
"totalCents": {
"type": "integer",
"minimum": 0
},
"supported": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 503.
Operation errors: CHOOSE_OFFER_REQUIRED, OFFER_CHANGED, CHECKOUT_OFFER_REQUIRED, CHECKOUT_OFFER_VERSION_CONFLICT, SUBSCRIPTION_CART_UNSUPPORTED.
/api/checkout/location-evidence
Obtain short-lived, edge-observed buyer location evidence for custom website quoting.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Origin/storefront-bound edge-observed location proof, not account authorization.
- Request fields
- query headlessOrigin: string (required)
- query storefrontSlug: string (required)
- Returns
- An opaque evidence token and expiresAt, or 503 if the edge adapter is not configured.
- Notes
- Call directly from the buyer browser using credentials: omit. Cloudflare signs its observed country and a visitor-IP hash for this origin/storefront, valid for five minutes. Pass evidence in the quote body. Your private platform forwards the actual visitor IP with its verified website key; the platform validates the signature and context. It never grants account, payment or tax-setting permissions. SoundSync must route this endpoint through its edge adapter; do not give signing secrets to developers. Fetch directly from the buyer browser using credentials:omit and Origin matching headlessOrigin. Discover the separate public issuer via payment-methods.locationEvidenceOrigin; do not assume the API origin serves the edge adapter. The five-minute proof binds observed country and visitor-IP hash. Forward as locationEvidenceToken through your private website platform with genuine visitor-IP context. A website key cannot sign this proof. Missing configured edge support returns 503; do not bypass tax evidence checks.
Request, response and error reference
Query and header parameters
[
{
"name": "headlessOrigin",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "storefrontSlug",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"evidence": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true,
"required": [
"evidence",
"expiresAt"
]
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/checkout/tax-jurisdictions
List tax jurisdictions available to checkout quoting.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Product or storefront scoped
- Returns
- Country/jurisdiction list used by checkout tax UI.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"countryName": {
"type": "string"
},
"regions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"regionCode": {
"type": "string"
},
"regionName": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
/api/checkout/status
Read confirmed checkout/fulfillment status for the purchasing customer.
- Auth
- Account Bearer session token
- Scope
- Verified purchasing customer, matching storefront and platform payment environment.
- Request fields
- query sessionId: string (required)
- query storefrontSlug: string (required)
- Returns
- Status, fulfilled flag, provider, currency, totalCents and taxAmountCents. Current library entitlements determine present access.
- Notes
- Read-only; never captures payment or grants a license. Buyer, storefront and platform payment environment must match. Read-only: never captures payment, creates access or pays earnings. A success URL is not payment proof. Current library entitlements determine access after a refund or revocation.
Request, response and error reference
Query and header parameters
[
{
"name": "sessionId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "storefrontSlug",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"fulfilled": {
"type": "boolean"
},
"provider": {
"type": "string",
"enum": [
"stripe",
"paypal"
]
},
"currency": {
"type": "string"
},
"totalCents": {
"type": [
"integer",
"null"
]
},
"taxAmountCents": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/checkout/external
Open the saved FastSpring, Gumroad or WooCommerce product checkout.
- Auth
- Account Bearer session token
- Scope
- Verified customer session and independently verified website; one active allowed product/provider/environment mapping.
- Request fields
- provider: fastspring | gumroad | woocommerce (required)
- productId: integer (required)
- storefrontSlug: string (required)
- headlessOrigin: string (required)
- externalEnvironment: test | live
- Returns
- Saved allowlisted external URL and paymentFlow: external.
- Notes
- External licensing, not Full Store. Choose externalEnvironment test/live independently of Stripe settings. An active mapping, verified website and owned available serial product are required. This redirect never grants a license or credits SoundSync payouts. Full Store uses the managed quote/product checkout routes instead. External licensing, not Full Store. externalEnvironment defaults to live and is independent of Stripe/PayPal environment. Opens only the saved allowed URL. It never calculates SoundSync tax, captures/confirms payment or grants a license. A provider return URL is not SoundSync checkout-status confirmation.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"fastspring",
"gumroad",
"woocommerce"
]
},
"productId": {
"type": "integer",
"minimum": 1
},
"storefrontSlug": {
"type": "string"
},
"headlessOrigin": {
"type": "string"
},
"externalEnvironment": {
"type": "string",
"enum": [
"test",
"live"
]
}
},
"additionalProperties": true,
"required": [
"provider",
"productId",
"storefrontSlug",
"headlessOrigin"
]
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"provider": {
"type": "string"
},
"paymentFlow": {
"const": "external"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/embed/storefront/:storeSlug/cart
Accept client-side cart state for embedded storefront display.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Product or storefront scoped
- Request fields
- items: array
- Returns
- Accepted cart echo plus checkout endpoint. Checkout recalculates server-side.
- Notes
- An echo for client cart display, not a priced or authorized server cart. Use /api/checkout/product for current checkout creation.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"cart": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"serverCalculated": {
"const": false
}
},
"additionalProperties": true
},
"checkoutEndpoint": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/embed/storefront/:storeSlug/cart/items
Accept one embedded cart item for display.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Product or storefront scoped
- Request fields
- productId: integer
- quantity: integer
- Returns
- Accepted item echo plus checkout endpoint.
- Notes
- Echoes the body for display; does not reserve inventory, validate totals or start payment.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"item": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"checkoutEndpoint": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/embed/storefront/:storeSlug/cart/coupon
Attach a coupon/promo code to embedded cart display.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Product or storefront scoped
- Request fields
- code: string
- coupon: string
- Returns
- Coupon echo. Final validation happens during server-side checkout.
- Notes
- Echoes code or coupon only. Final validation occurs during checkout; a successful echo is not a valid discount.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"coupon": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"coupon": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/embed/storefront/:storeSlug/checkout
Embedded checkout handoff route.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Product or storefront scoped
- Returns
- 409 response pointing clients to /api/checkout/product.
- Side effects
- None; returns a compatibility response pointing to canonical product checkout.
- Notes
- This endpoint exists to keep embedded clients on the canonical checkout creation route. Compatibility endpoint; does not create checkout. Send authenticated checkout requests to /api/checkout/product.
Request, response and error reference
No request body fields are read by this operation.
HTTP 409 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "USE_PRODUCT_CHECKOUT_ENDPOINT"
},
"message": {
"type": "string"
},
"checkoutEndpoint": {
"const": "/api/checkout/product"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
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 | Hosted return routes remain validated and canonicalized. For an external frontend, use a verified website configuration. |
| headlessOrigin + storefrontSlug + quoteId | Approved external website checkout. SoundSync uses the saved callback paths and validates the server quote against buyer, cart, location and environment. |
SoundSync
Custom websites with any framework
Use our HTTPS/JSON APIs from your own platform in any language. Keep your existing frontend and hosting while SoundSync manages customer accounts, tax, checkout, licensing and delivery.
| Step | Implementation |
|---|---|
| Connect your website | In Developer → Brand Domain → External website, save the HTTPS origin, copy the private server connection key, add the TXT ownership record and verify. Keep your current hosting records. |
| Choose your implementation | Call the documented HTTP APIs directly using your platform language. The Astro / Node starter in External website settings is an optional shortcut, not an API requirement. See Custom Website API for the framework-neutral flow. |
| Customer accounts | Use account APIs through your own platform. Keep tokens in server-side sessions. Verified external callbacks support email verification and password recovery on your site. POST verification can return JSON when Accept is application/json. |
| Tax and payment | Render country/region choices from tax-jurisdictions, show a server quote and redirect to SoundSync-managed Stripe or PayPal checkout. SoundSync remains the merchant. Subscriptions use Stripe. |
| Confirmation and delivery | GET /api/checkout/status?sessionId=...&storefrontSlug=... requires the purchasing customer session. Only confirmed fulfillment grants access; current library entitlements authorize direct signed R2 downloads. |
| Fees and payouts | Use the current pricing and legal pages. Accounting and actual provider-fee deductions remain centralized in SoundSync; the connector does not calculate developer fees or send payouts. |
SoundSync
