API reference
Testing and production activation
Evaluate a custom website, claim free products, handle customer sessions and deliberately activate live service billing.
SoundSync
Environment and billing boundaries
Keep Test & Launch, External website settings and Billing together in your setup flow.
| Action | Behavior |
|---|---|
| Evaluate | Use separate test developer/customer accounts, products, private website key, callback origin, payment sandbox credentials and files. Set SOUNDSYNC_EXPECTED_ENVIRONMENT=test and send X-SoundSync-Expected-Environment: test from your platform. Evaluation cannot collect developer service invoices or send payouts. |
| Try JUCE immediately | Open Website Builder → Evaluation / Practice Area → Create my JUCE demo. No product fields or service selection required. Download preconfigured JUCE source, activate a seven-day serial and use the private developer inbox for verification. The demo stays outside your catalog. |
| Handle sessions | Account tokens expire after 30 days; JSON login includes session.expiresAt and refreshSupported:false. No refresh endpoint is available. Starter website sessions default to 24 hours. Store tokens privately and ask for sign-in again after expiry or a 401. |
| Claim TailFit | Configure the server product at $0 with delivery files and optional serial licensing. A verified customer claims through POST /api/checkout/claim, then reads their scoped library and authorized download. A paid product is rejected without opening checkout. |
| Activate production | The live developer account owner reviews pricing on Billing and explicitly activates the selected service. Draft setup and isolated evaluation do not start monthly billing. Publishing a product or generating serials requires activation first; these actions no longer silently activate billing. Existing active service and customer access are preserved. |
| Keep your website | Registration, login, recovery, store and library pages can use your own design. Full Store paid checkout uses SoundSync-managed Stripe/PayPal and server tax quotes. Free claims bypass payment. |
SoundSync
Free-only claim
Your platform fixes the storefront, verified website origin and product ID. The action accepts no browser price and creates no paid provider checkout.
SoundSync
Private JUCE practice demo
Owner-only in the isolated evaluation environment. Uses the regular licensing API and private test inbox; no demo is inserted into your catalog.
SoundSync
Explicit service activation
Owner-only, all-product billing scope. Confirm current pricing before production; this action activates the agreement rather than sending a payment.
Evaluate a custom website before live commerce
Keep your own frontend and Node, PHP or other platform. Full Store uses SoundSync's managed checkout and tax calculation; external licensing keeps payments and tax with the external provider. Website design and payment ownership are separate choices.
Choose the API environment first
Open Website Builder → Evaluation / Practice Area (the last menu item). The verified developer account owner selects Create or recover practice account, opens the private invitation and chooses a separate practice password. Invitations expire after 10 minutes and work once. Existing practice users can sign in directly; recovery uses a fresh invitation from the production owner account. Billing, Custom API and Product Preview also link to the evaluation instructions. Until the separate hosted address is configured and deployed, this page explains local setup instead of showing an invented sandbox URL.
An evaluation deployment has its own database, developer/customer accounts, products, website verification/key, payment credentials, webhook secrets and private files. To test your own storefront, choose a service option, create a test copy of TailFit and publish it in practice. To test JUCE licensing first, use the demo below instead: no product or service setup is needed. No production activation is required in practice. Never copy production customers, passwords, payment methods, private website keys or billing agreements into evaluation. Practice includes 2 GB of test delivery files; no storage action starts paid service.
Try JUCE without creating a product
Inside Website Builder → Evaluation / Practice Area, choose Create my JUCE demo. This creates a private sample outside your catalog, along with a seven-day temporary serial. It does not ask for product descriptions, artwork, files, store settings, checkout or a service selection. Each practice workspace has its own demo and serial; the demo cannot be published or sold from your catalog.
Choose Prepare JUCE demo download, then download the private ZIP. It contains the normal JUCE integration source, preconfigured for the Practice API, demo product/app ID and independent offline verification keys, plus START-HERE-PRACTICE.txt. Use your existing JUCE checkout to build the included standalone/plugin example or add the drop-in component to a test plugin. It is source code, not a precompiled plugin.
Enter the demo serial and a test customer email in the plugin. Open Developer test inbox on this same Practice page, verify the license link, then return to the plugin to finish activation (Restore if prompted). Test validation, offline grace and deactivation. The temporary license caps offline access at its expiry. Reset demo license revokes the old serial and online activations and issues a fresh seven-day serial; a device already offline follows its previously signed grace deadline. Download a fresh package after resetting if you want its included serial instructions updated.
The normal catalog and customer-store journey remain separate. When ready to test your own free product, follow the TailFit flow below. When shipping a real plugin, create your real product and generate its production JUCE package; demo IDs and serials only work in Practice. For local operator rehearsals, the generated demo permits HTTP only to its exact loopback origin and the local launcher must keep running. Hosted Practice uses HTTPS; regular production JUCE packages remain HTTPS-only.
The Developer test inbox appears on the same Practice Area page inside the separate environment. It retains the latest 100 messages for that workspace. Refresh after registering a test customer or requesting recovery; open a message for its safe verification/reset links. Use a private window or separate browser profile for the customer, keeping the developer window signed in. Test emails are captured privately and never sent through Resend or Elastic. Other developers cannot read this workspace's messages or use its test customer's account.
Your private website configuration must select both the supplied evaluation origin and SOUNDSYNC_EXPECTED_ENVIRONMENT=test. New kits send X-SoundSync-Expected-Environment: test; an API mismatch stops the request before account, claim or payment actions. A public request field cannot select the payment environment. A staging website connected to https://www.soundsync.dev still uses production.
SoundSync
Try JUCE without creating a product
SOUNDSYNC_API_ORIGIN=https://THE-EVALUATION-API-SUPPLIED-BY-SOUNDSYNC
SOUNDSYNC_EXPECTED_ENVIRONMENT=test
SOUNDSYNC_STOREFRONT=YOUR-TEST-STOREFRONT
SOUNDSYNC_WEBSITE_KEY=YOUR-PRIVATE-TEST-WEBSITE-KEY
WEBSITE_ORIGIN=https://YOUR-VERIFIED-STAGING-WEBSITE
SOUNDSYNC_WEBSITE_MODE=full_store
SOUNDSYNC_CHECKOUT_PROVIDER=soundsync
Try JUCE without creating a product
Restart your private platform after changing these values. Use separate deployments or environment files for test and live; never overwrite a running live website's callbacks or key to perform a test. Test checkout must use the provider's displayed sandbox/test account or test card, never saved real payment details.
Accounts and session expiry
Register with POST /api/auth/register, verify the one-use email link through POST /api/auth/verify-email, then call POST /api/auth/login. Fix role: customer and storefrontSlug on your platform. Registration does not sign the customer in.
The account token expires after 30 days, with earlier invalidation possible after logout or account-security changes. JSON login now includes session.expiresAt, session.expiresInSeconds and session.refreshSupported: false. There is no refresh-token endpoint. Prompt for sign-in again after expiry or a 401. Never store a customer's password to silently repeat login.
The starter website's private server session defaults to 24 hours, independently of the account token. Node/PHP handlers keep the token off the browser and clear expired/revoked sessions. Use HttpOnly, Secure, SameSite cookies and private session storage. A longer website cookie does not extend an API token's expiry.
TailFit and other free products
Configure a one-time SoundSync product whose server-calculated price is $0. Attach its hosted delivery files, enable downloads and enable serial licensing if the plugin needs it. In evaluation, publish the test copy. Production publication requires explicit service activation first. Marketplace listing is not required for a direct website claim.
The customer selects TailFit in the catalog, opens its product page and chooses Get it free. Guests register or sign in first, verify their email, then return to that product to claim it. Native verification links preserve the product destination. Starter kits preserve the selected product/offer through registration, verification and sign-in in the website's private session, scoped to that customer. The claim adds the product to the library and opens account downloads. There is no free-download button on the checkout page or inside the library's purchase form. This applies to SoundSync storefronts and all custom website starter kits, including Astro, Next.js, Nuxt, SvelteKit, Express, PHP, Laravel and WordPress.
After verified customer sign-in, the product-page action calls your private platform, which calls:
SoundSync
TailFit and other free products
POST /api/checkout/claim
Authorization: Bearer CUSTOMER-ACCOUNT-TOKEN
X-SoundSync-Website-Key: PRIVATE-WEBSITE-KEY
X-SoundSync-Client-IP: VERIFIED-VISITOR-IP
X-SoundSync-Expected-Environment: test
Content-Type: application/json
{"productId":123,"storefrontSlug":"YOUR-TEST-STOREFRONT","headlessOrigin":"https://YOUR-VERIFIED-STAGING-WEBSITE"}
TailFit and other free products
The server validates the product, website, customer scope and actual price. A positive amount returns PRODUCT_NOT_FREE; the action never starts paid checkout. A successful response has claimed: true, freeClaim: true, checkoutBypassed: true and an order ID. Repeated claims return the existing claim with alreadyClaimed: true. A $0 claim needs no payment method or paid-checkout billing-address form.
Then request GET /api/library?storefront=YOUR-TEST-STOREFRONT with that customer's token. Use the returned delivery references through the private platform. The authorized delivery endpoint issues a short-lived private R2 redirect; never publish a permanent raw file URL or grant access from a success-page query parameter.
The shared Node client exposes client.claim({productId}, token). Kits expose the same authenticated action at their private /api/soundsync/claim route. Starter catalog/product pages live at /products and /products/PRODUCT-SLUG (or /products?slug=PRODUCT-SLUG). WordPress uses [soundsync_products] and [soundsync_product slug="tailfit"]; put [soundsync_account] on /account and [soundsync_checkout] on /checkout. For configured purchase offers, pass the selected offerId, offerVersionId and priceVersionId; the server still calculates the price. External-provider purchases and free claims remain owned by that provider. The older /api/checkout/product free-claim API remains compatible, but new customer interfaces use the product page.
Paid checkout and the full journey
Keep your store, account, recovery and library pages. Paid checkout obtains countries/regions and a fresh server tax quote, then creates the SoundSync-managed Stripe or PayPal checkout. The buyer finishes on the provider's secure page. SoundSync's verified confirmation creates access; returning to your website does not prove payment.
Check registration, verification, login/logout, recovery, TailFit claim, repeated claim, a paid provider test purchase, pending/failed/cancelled return, license/library delivery, unauthorized download denial, duplicate notification, full test refund and revoked access. Simulated local providers test application behavior; only a provider-executed sandbox transaction verifies the hosted provider connection. Keep both types of evidence labeled accurately.
The billing boundary
Selecting a service and preparing drafts do not start monthly service billing. Isolated evaluation does not create collectible SoundSync service invoices or send developer payouts, and it does not activate itself after a period of time.
When ready, return to the live developer account → Billing → Your SoundSync services. The developer account owner reviews the current selected pricing and explicitly chooses Activate live commerce (Full Store) or Activate production service (licensing options). Confirming activates the agreement; it does not itself send a payment. The applicable calendar-month service minimum/fixed fee is not prorated. Email/redemption usage and actual provider fees follow the current published pricing separately.
Before activation, production stores remain drafts. Known public storefront/custom-domain/embed pages show a minimal Coming soon page; public catalog APIs do not expose their products. New store-customer registration, checkout (including quotes and new free claims), new serial/license grants, external sales connections and real marketing delivery require an already activated service. Draft editing and local uploads within the draft allowance remain available. Publishing and licensing never activate billing implicitly. Existing customer sign-in and recovery keep using the verified account callbacks even if the storefront is a draft.
Activation is one-way and idempotent. The button confirms the exact agreement shown on Billing; if another tab changes it, refresh and review its pricing again. Service selection is locked while funding and activation are checked. The interface offers no switch to turn a live membership off. A future pause/cancel process is separate. Existing active agreements, previously issued licenses, customer recovery and authorized downloads are preserved.
Local operator setup
Install the repository dependencies, have PostgreSQL binaries available (PG_BIN if needed), then run from this local checkout:
SoundSync
Local operator setup
$env:NODE_ENV = 'development'
npm run evaluation:start
Local operator setup
The launcher creates its own loopback PostgreSQL cluster, marked soundsync_evaluation database, local S3-compatible storage, independent authentication/encryption/offline-signing keys and private email capture. It ignores production environment files. Open http://127.0.0.1:4080/signup, create a fictional developer account, then visit /developer/practice. All state stays in .evaluation/local under this checkout; Ctrl+C stops services and keeps practice data. It is a local storage rehearsal, not proof of hosted R2/provider connectivity.
Free claims and private uploads/downloads work without payment credentials. Upload local test files; remote URL imports are disabled in practice. For paid tests only, fill .evaluation/local/sandbox-providers.json with isolated Stripe test and/or PayPal sandbox credentials, then restart. Its allowlist rejects live Stripe keys and unrelated settings; do not paste secrets into chat or commit the file. Fixed test buyer-country evidence is labeled simulated. Live keys, known production origins, unsafe buckets and mismatched database identities prevent evaluation startup. Automatic workers and financial sending stay disabled.
For a hosted environment, the SoundSync operator follows deploy/evaluation/README.md in the application repository and the separate platform/practice configuration templates. Provisioning/deployment is an operator step, not performed by this local update. Paid custom-site tax tests also require a separate evaluation location-evidence issuer and secret; follow [Headless tax evidence](./headless-tax-evidence.md). Never expose the private mail directory as static content. The authenticated workspace inbox is the supported developer interface.
