Skip to content
SoundSyncAudio software platform

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

OperationContract and boundary
Register and verifyPOST /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 recoverPOST /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 checkoutDiscover 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 checkoutPOST /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 deliverGET /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 outPOST /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

Server-side Full Store configuration
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

GET /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.

PUT /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.

POST /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.

DELETE /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.

GET /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.

GET /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.

POST /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.

GET /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.