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.
/api/checkout/payment-methods
Read the currently configured checkout payment choices.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Configured platform payment methods, without customer or product ownership data.
- Returns
- 200 { methods: { stripe, paypal } }. Provider configuration does not prove that a particular product or subscription is eligible.
- Side effects
- None.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"methods": {
"type": "object",
"properties": {
"stripe": {
"type": "boolean"
},
"paypal": {
"type": "boolean"
}
},
"required": [
"stripe",
"paypal"
],
"additionalProperties": true
},
"runtime": {
"type": "object",
"properties": {
"environment": {
"enum": [
"test",
"live"
]
},
"evaluation": {
"type": "boolean"
},
"developerBillingEnabled": {
"type": "boolean"
},
"evaluationOrigin": {
"type": [
"string",
"null"
],
"format": "uri"
}
},
"additionalProperties": true
},
"customerSession": {
"type": "object",
"properties": {
"tokenLifetimeSeconds": {
"type": "integer",
"minimum": 0
},
"refreshSupported": {
"const": false
},
"websiteSessionDefaultSeconds": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"locationEvidenceOrigin": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Public buyer-browser proof issuer; may differ from the API origin."
}
},
"additionalProperties": true,
"required": [
"methods"
]
}
/api/checkout/product
Create Stripe or PayPal managed checkout, or resolve a supported free claim.
- Auth
- Account Bearer session token
- Scope
- Product owner, storefront ownership, marketplace attribution, and customer identity are resolved server-side.
- 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
- 201 with provider stripe or paypal, checkoutSessionId, url and applicable stripeMode/paypalMode/saleChannel. A supported free claim returns provider manual with freeClaim, claimed, alreadyClaimed, orderId and url; an existing claim returns 200 rather than 201.
- Side effects
- Records checkout_started analytics, stores checkout session, records abandoned checkout signal, may create free order/entitlement for free claims.
- Notes
- Follow the returned provider URL. PayPal supports one-time purchases, not subscriptions. Subscription checkout uses Stripe and one subscription product per request. Server pricing, the $9.99 paid floor, account verification, billing eligibility and commerce controls remain authoritative. Never grant access from a browser return alone. 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
Create a server tax/checkout quote for product checkout.
- Auth
- Optional authentication OR Account Bearer session token
- Scope
- Use the authentication and resource scope specified for this operation.
- 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
- 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. 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/tax-jurisdictions
List checkout-supported tax jurisdictions.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Use the authentication and resource scope specified for this operation.
- Returns
- countries[] supported by the internal tax jurisdiction service.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
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/embed/storefront/:storeSlug/checkout
Compatibility endpoint for embedded storefront checkout attempts.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Use the authentication and resource scope specified for this operation.
- Returns
- 409 USE_PRODUCT_CHECKOUT_ENDPOINT and checkoutEndpoint /api/checkout/product.
- Side effects
- None; returns a compatibility response pointing to canonical product checkout.
- Notes
- Embedded storefront checkout is intentionally handed off to canonical product checkout. 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.
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.
PayPal approval and completion
Read GET /api/checkout/payment-methods, then select paymentProvider: paypal for an eligible one-time checkout or stripe for card/wallet checkout. Both use the same canonical product checkout endpoint. PayPal is not a subscription payment option.
Open the returned provider URL. The configured PayPal return/cancel routes handle the provider handoff; they are not generic client capture APIs and must not be polled or replayed. Confirm the resulting order and authorized customer access after server reconciliation. Closing the provider page or visiting a success URL is not proof of payment.
Product news and marketing preferences
Purchases and storefront customer signups automatically add customers to the relevant developer marketing list. Account and checkout forms do not require a separate marketing opt-in checkbox. Necessary receipts, security and product-access messages remain separate from marketing campaigns.
Saved unsubscribes, complaints, refusals and suppressions remain protected. Signing in, correcting an email or buying again does not silently erase a saved restriction. Marketing messages include an unsubscribe link. Developers remain responsible for the rules applicable to their promotional messages; automatic enrollment is not evidence of affirmative advertising-measurement consent.
Cart-link URLs are not checkout requests
ss_cart is a storefront URL parameter containing product IDs, not a new API request body, customer token, discount instruction or server reservation. The browser reads the public storefront products, checks eligibility and merges its cart; a link does not collect payment.
Continue through the documented canonical product checkout operation. The server recalculates the current products, offers and tax and applies the usual account and minimum-price requirements.
SoundSync
Build and test the email button
Campaign and cart-link guide
Copy or insert the link and verify the actual destination before sending.
SoundSync
