Documentation
Custom Website API
Connect your existing frontend and platform to verified accounts, managed checkout and private customer access.
Any platform, one customer flow
Use HTTPS/JSON from your own server. PHP, Python, Ruby, Go, Java, .NET and JavaScript can implement the same contracts; no Astro or Node runtime is required by the API. Your browser calls your platform, which fixes the storefront/customer scope and keeps bearer and MFA tokens in private sessions.
SoundSync
Connect the customer journey
| Operation | Contract and boundary |
|---|---|
| Register and verify | POST /api/auth/register with role:customer and storefrontSlug; ordinary registration returns 202, not a session. Its email returns to the saved verification callback. POST /api/auth/verify-email with Accept:application/json, then sign in separately. |
| Sign in and recover | POST /api/auth/login and complete any returned MFA challenge privately. Forgot/reset-password use the saved store callback and one-use proof. Store credentials and shared credentials retain their separate boundaries. |
| Quote managed checkout | Discover supported countries/regions and payment methods. Obtain buyer-browser location evidence, pass it through your private platform and show the server subtotal, tax and total. Refresh expired or changed quotes. |
| Create checkout | POST /api/checkout/product using the same buyer, cart/location, storefrontSlug, headlessOrigin and quoteId. One-time Stripe/PayPal and Stripe subscriptions retain their existing rules. |
| Confirm and deliver | GET /api/checkout/status for the purchasing customer. Provider-confirmed fulfillment, not a browser URL, grants access. The current storefront-scoped library authorizes private downloads. |
| Sign out | POST /api/auth/logout before destroying the local session. A 503 revocation error needs recovery; deleting a browser token alone is not confirmed server revocation. |
Keep buyer evidence independent
Read locationEvidenceOrigin from /api/checkout/payment-methods. The browser requests the location proof directly from that public issuer, without cookies or tokens; it can be a different origin from the API. Send headlessOrigin and storefrontSlug. The five-minute proof binds the edge-observed country and visitor-IP hash.
Your private platform forwards locationEvidenceToken and the genuine visitor IP with its website key. The key identifies a verified website; it does not sign tax evidence or authenticate a customer. Do not trust an arbitrary forwarding header, substitute your server IP or waive a blocking tax requirement. If CSP is enabled, permit the discovered proof issuer in connect-src.
Sessions and sensitive URLs
Keep server keys, customer tokens, MFA challenges and reset/verification proofs out of client storage, analytics and logs. Use private persistent sessions, HttpOnly/Secure/SameSite=Lax cookies, CSRF protection and no-referrer recovery pages. Multiple replicas need shared session storage. Do not cache account pages or private API responses. Download through short-lived authorized links instead of proxying large file bytes through your website.
SoundSync
Private website settings
SOUNDSYNC_API_ORIGIN=https://www.soundsync.dev
SOUNDSYNC_STOREFRONT=your-store
WEBSITE_ORIGIN=https://www.example.com
SOUNDSYNC_WEBSITE_KEY=<private-server-key>
SOUNDSYNC_WEBSITE_MODE=full_store
SOUNDSYNC_CHECKOUT_PROVIDER=soundsync
SoundSync
Use the complete contracts
Account API
Verification, MFA, recovery and session states.
Checkout API
Quote, payment and return-state handling.
Customer Library API
Current account ownership and download authorization.
External provider API
Keep provider payments without calling SoundSync tax for the same purchase.
SoundSync
Requests and responses
/api/developer/headless
Read external website settings
- Auth
- Account Bearer session token
- Scope
- Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.
- Returns
- 200: Inspect the response schema and conditional states.
- Notes
- The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"website": {
"type": [
"object",
"null"
],
"properties": {
"storefrontId": {
"type": "integer",
"minimum": 1
},
"storefrontSlug": {
"type": "string"
},
"origin": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"callbacks": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
},
"dns": {
"type": "object",
"properties": {
"type": {
"const": "TXT"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"defaults": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/developer/headless
Save external website origin and callbacks; rotate its key
- Auth
- Account Bearer session token
- Scope
- Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.
- Request fields
- origin: string (required)
- callbacks: object
- Returns
- 200: Inspect the response schema and conditional states.
- Notes
- The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"origin": {
"type": "string"
},
"callbacks": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true,
"required": [
"origin"
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"website": {
"type": [
"object",
"null"
],
"properties": {
"storefrontId": {
"type": "integer",
"minimum": 1
},
"storefrontSlug": {
"type": "string"
},
"origin": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"callbacks": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
},
"dns": {
"type": "object",
"properties": {
"type": {
"const": "TXT"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"defaults": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
},
"serverKey": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/developer/headless/verify
Verify the current website TXT record
- Auth
- Account Bearer session token
- Scope
- Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.
- Returns
- 200: Inspect the response schema and conditional states.
- Notes
- The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site. Rate limited to ten attempts per minute. A concurrent settings change returns WEBSITE_CHANGED instead of verifying the previous proof.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"website": {
"type": [
"object",
"null"
],
"properties": {
"storefrontId": {
"type": "integer",
"minimum": 1
},
"storefrontSlug": {
"type": "string"
},
"origin": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"callbacks": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
},
"dns": {
"type": "object",
"properties": {
"type": {
"const": "TXT"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"defaults": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 429, 500, 503.
/api/developer/headless
Remove the saved external website connection
- Auth
- Account Bearer session token
- Scope
- Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.
- Returns
- 200: Inspect the response schema and conditional states.
- Notes
- The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"website": {
"type": [
"object",
"null"
],
"properties": {
"storefrontId": {
"type": "integer",
"minimum": 1
},
"storefrontSlug": {
"type": "string"
},
"origin": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"callbacks": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
},
"dns": {
"type": "object",
"properties": {
"type": {
"const": "TXT"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"defaults": {
"type": "object",
"properties": {
"verification": {
"type": "string"
},
"reset": {
"type": "string"
},
"login": {
"type": "string"
},
"success": {
"type": "string"
},
"cancel": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/developer/headless/package
Download a website integration starter
- Auth
- Account Bearer session token
- Scope
- Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.
- Request fields
- query integration: string
- query mode: string
- Returns
- 200: Inspect the response schema and conditional states.
- Notes
- Default integration is astro-node and mode is full_store. External mode downloads are selected through fastspring, gumroad or woocommerce; the general framework cards select Full Store. Invalid combinations return 400. The ZIP is generated without live secrets or customer data. INTEGRATION.json records payment/tax responsibility. Merge routes deliberately; do not overwrite your existing project. Cache-Control: no-store.
Request, response and error reference
Query and header parameters
[
{
"name": "integration",
"in": "query",
"schema": {
"type": "string",
"enum": [
"astro-node",
"node-express",
"nextjs",
"nuxt",
"sveltekit",
"php",
"wordpress",
"fastspring",
"gumroad",
"woocommerce"
]
}
},
{
"name": "mode",
"in": "query",
"schema": {
"type": "string",
"enum": [
"full_store",
"external"
]
}
}
]
No request body fields are read by this operation.
HTTP 200 response (application/zip)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/checkout/status
Read confirmed checkout state 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
- 200: Inspect the response schema and conditional states.
- Notes
- 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 provider checkout URL
- 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
- 201: Inspect the response schema and conditional states.
- Notes
- 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/checkout/location-evidence
Obtain a short-lived buyer-browser location proof
- 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
- 200: Inspect the response schema and conditional states.
- Notes
- 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.
