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
}
},
"required": [
"methods"
],
"additionalProperties": true
}/api/checkout/product
Create Stripe or PayPal managed checkout, or resolve a supported free claim.
- Auth
- Account Bearer JWT
- 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
- storefrontSlug: string
- paymentProvider: stripe | paypal
- marketingOptIn: boolean
- marketingOptOut: boolean
- 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.
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",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"productId"
],
"additionalProperties": true
}
},
"promoCode": {
"type": "string"
},
"taxQuoteId": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
},
"paymentProvider": {
"enum": [
"stripe",
"paypal"
]
},
"marketingOptIn": {
"type": "boolean"
},
"marketingOptOut": {
"type": "boolean"
}
},
"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.
/api/checkout/quote
Create a server tax/checkout quote for product checkout.
- Auth
- Optional authentication OR Account Bearer JWT
- 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
- 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.
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
}
},
"required": [
"productId"
],
"additionalProperties": true
}
},
"countryCode": {
"type": "string"
},
"regionCode": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"promoCode": {
"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.
/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
Eligible purchases, subscriptions, and account activity automatically add customers to the relevant developer's marketing audience. Cart, checkout review, checkout sign-in, and subscription-plan cards do not ask for a marketing choice. Standalone storefront customer sign-in and account creation retain the Do not add me to product news and offers choice.
Automatic enrollment preserves saved refusals, unsubscribes, and suppression records. Marketing messages include an unsubscribe link. Necessary receipts and account/access messages remain separate.
SoundSync