Documentation

Developer docs for licensing, storefronts, customer library, and plugin integrations.

This public reference uses actual route names where available. Dashboard-only notes call out areas where public API examples are still expanding so developers can plan integrations without relying on invented endpoints.

Quick activation example

curl -X POST "$SOUNDSYNC_API_BASE/api/license/v1/activate" \
  -H "Authorization: Bearer PLUGIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"CUSTOMER_SERIAL","machine_id":"DEVICE_ID"}'

Quickstart

Create a developer account, create a product, configure one-time pricing or subscriptions, generate product plugin credentials, validate/activate a serial, test checkout/storefront, and confirm customer library downloads.

Authentication

Use developer JWTs for dashboard APIs and product-scoped plugin credentials for licensing calls. Store secrets server-side where possible and rotate exposed credentials.

Product credentials

Product/plugin keys are scoped per product. Secrets should be revealed carefully, rotated when exposed, and revoked when an integration is retired.

Product delivery

Use managed upload jobs for local product files and upload-by-link imports, then serve customer downloads through entitlement-gated delivery routes instead of public raw storage URLs.

Managed upload routes

POST /api/products/:productId/files/uploads
POST /api/products/:productId/files/upload-link
GET /api/products/:productId/files/uploads
POST /api/products/:productId/files/uploads/:jobId/cancel
POST /api/products/:productId/files/uploads/:jobId/retry

Product subscriptions

Configure subscription settings from product tools, test subscription checkout, and keep subscription status aligned with entitlements, serials, customer library access, and plugin validation.

CheckoutEntitlementLicense

Subscription lifecycle

Enable product subscription settings\nPOST /api/checkout/product -> mode: "subscription"\nCheckout lifecycle event -> subscription row + order + entitlement + serial\nPlugin validation -> unlock only while subscription access is valid

Scheduled deals

Schedule product deal windows, edit upcoming deals, cancel scheduled deals, and create campaign drafts around promotions from authenticated developer workflows.

Scheduled deal routes

GET /api/products/:productId/deals
POST /api/products/:productId/deals
PATCH /api/products/:productId/deals/:dealId
POST /api/products/:productId/deals/:dealId/cancel
POST /api/developer/marketing/scheduled-deals/:dealId/campaign-draft

Licensing API

Validate serials, subscription access, activate machines, deactivate machines, restore/check activation, refresh license status, and respect offline grace and invalid license states.

Licensing route family

POST /api/license/v1/validate
POST /api/license/v1/activate
POST /api/license/v1/deactivate
POST /api/license/v1/claim-status

Storefront API

Public storefront/product routes expose brand, product cards, images, pricing/sale price/subscription eligibility, visibility, and checkout eligibility.

Customer Library / Delivery

Customer library and delivery routes should respect ownership, entitlements, protected downloads, serial/license display, and signed or backend-gated file access.

Webhooks

Webhook management is available for developer integrations. Event coverage continues to expand, so confirm required events before production automation.

Email Marketing

Dashboard-based campaign workflows are available for drafts, eligible audience selection, consent checks, send estimates, scheduled-deal campaign drafts, and reporting. Public API docs will expand as contracts are locked.

Dashboard workflow

Use the dashboard Email Marketing Center for drafts, eligible audience selection, consent checks, send estimates, scheduled-deal campaign drafts, and reporting while public API examples continue to expand.

Error codes

Handle invalid credentials, revoked key, invalid serial, suspended license, expired license, product mismatch, rate limit, and network unavailable states explicitly.

Example error response

{
  "ok": false,
  "error": "product-mismatch",
  "message": "Serial does not unlock this product."
}

Rate limits

Respect rate limits on auth, licensing, checkout, and public storefront routes. Follow next_check_secs when validation responses include it.

HISE plugin storefront

Generate the product HISE package from the saved product page, configure storefront slug and public catalog URLs, test Store/My Products and central support routing, open checkout externally, and keep downloads entitlement-gated.

StoreMy ProductsExternal checkout

HISE product package

Product page -> Download HISE Package\ninclude("SoundSync/Runtime/SoundSyncRuntime.js")\nSoundSyncConfig.storefrontSlug = "STORE_SLUG"\nSoundSyncConfig.apiBase = "$SOUNDSYNC_API_BASE"\nCheckout opens in the default browser; support opens the central SoundSync support center; downloads use SoundSync delivery routes.

HISE integration

Use the guided HISE package path, product credentials, subscription-aware license settings, activation overlay, central support routing, offline cache behavior, and test connection workflows.

HISE packageActivation overlayStore + My Products

HISE config shape

SoundSyncConfig.productId = "PRODUCT_ID"\nSoundSyncConfig.apiBase = "$SOUNDSYNC_API_BASE"\nSoundSyncConfig.supportUrl = "$SOUNDSYNC_WEB_BASE/support"\nSoundSyncConfig.licenseModel = "subscription"\nSoundSyncConfig.subscriptionRequired = true\nSoundSyncConfig.storefrontSlug = "STORE_SLUG"

Custom/JUCE integration notes

Use API-first integration guidance for custom and JUCE products. Do not assume a complete JUCE SDK exists until it is explicitly shipped.

HTTPPlugin secretLock states

Custom integration flow

validate(serial, machineId)\n  -> POST /api/license/v1/validate\n  -> unlock only when status is active\n  -> lock on revoked, suspended, expired, or product-mismatch

Testing mode / sandbox notes

Use demo products, test checkout, generated credentials, fake customer data, and non-real payment data when validating workflows.

API reference

Endpoint cards

Authentication, product subscriptions, product credentials, plugin keys/secrets, validate serial, activate serial, deactivate machine, restore activation, refresh license, storefront products, customer library, webhooks, and error handling.

Licensing API

Activate serial

POST /api/license/v1/activate

Initial online activation is required before offline grace can apply.

Request

{
  "license_key": "CUSTOMER_SERIAL",
  "product_id": "PRODUCT_ID",
  "machine_id": "DEVICE_ID",
  "plugin_version": "1.0.0"
}

Response

{
  "ok": true,
  "validation_token": "token_from_activation",
  "offline_grace_days": 7,
  "next_check_secs": 86400
}

Licensing API

Validate serial

POST /api/license/v1/validate

Call before unlocking protected features. Confirmed invalid states should lock immediately.

Request

{
  "license_key": "CUSTOMER_SERIAL",
  "machine_id": "DEVICE_ID",
  "validation_token": "TOKEN_FROM_ACTIVATION"
}

Response

{
  "ok": true,
  "status": "active",
  "next_check_secs": 86400
}

Licensing API

Deactivate machine

POST /api/license/v1/deactivate

Release a machine and clear local plugin license state after success.

Request

{
  "license_key": "CUSTOMER_SERIAL",
  "machine_id": "DEVICE_ID",
  "validation_token": "TOKEN_FROM_ACTIVATION"
}

Response

{
  "ok": true,
  "status": "deactivated"
}

Licensing API

Claim and restore activation

POST /api/license/v1/claim-status

Use with /api/license/v1/claim when identity or email verification is required.

Request

{
  "license_key": "KNOWN_SERIAL",
  "product_id": "PRODUCT_ID",
  "machine_id": "DEVICE_ID"
}

Response

{
  "ok": true,
  "claim_status": "verified"
}

Plugin credentials

Product credentials

GET/POST /api/developer/plugin-keys/products/:productId

Developer-authenticated endpoint for creating and reading product/plugin credentials.

Request

POST /api/developer/plugin-keys/products/123
Authorization: Bearer DEVELOPER_JWT

Response

{
  "productId": 123,
  "pluginKeyPreview": "pk_live_...",
  "rotateKeyEndpoint": "/api/developer/plugin-keys/products/123/rotate-key"
}

Product delivery

Create local upload job

POST /api/products/:productId/files/uploads

Developer-authenticated multipart upload for managed product files. The job validates type/size, stores the file, and attaches it to the product.

Request

POST /api/products/123/files/uploads
Authorization: Bearer DEVELOPER_JWT
Content-Type: multipart/form-data

file=@Moonwave-FX.zip

Response

{
  "job": {
    "status": "attached",
    "progress": 100,
    "sourceType": "local_upload"
  },
  "file": { "url": "product-files/..." }
}

Product delivery

Create upload-by-link job

POST /api/products/:productId/files/upload-link

Developer-authenticated remote import job for HTTPS product file links. SoundSync blocks local/private hosts, unsafe protocols, oversized files, and excessive redirects before attaching the file.

Request

{
  "url": "https://downloads.example.com/Moonwave-FX.zip",
  "displayFilename": "Moonwave-FX.zip"
}

Response

{
  "job": {
    "status": "queued",
    "sourceType": "remote_url",
    "progress": 0
  }
}

Product delivery

Read upload jobs

GET /api/products/:productId/files/uploads

Load recent local and remote upload jobs for a developer-owned product.

Request

GET /api/products/123/files/uploads
Authorization: Bearer DEVELOPER_JWT

Response

{
  "jobs": [
    { "id": "501", "status": "attached", "progress": 100 }
  ]
}

Product delivery

Cancel or retry upload job

POST /api/products/:productId/files/uploads/:jobId/cancel or /retry

Cancel active jobs or retry failed/canceled upload-by-link jobs. Local uploads require choosing the file again.

Request

POST /api/products/123/files/uploads/501/retry
Authorization: Bearer DEVELOPER_JWT

Response

{
  "job": {
    "id": "501",
    "status": "queued",
    "progress": 0
  }
}

Product delivery

Manage product files

GET/POST/PATCH/DELETE /api/products/:productId/files

Developer-authenticated product file list, add, update, and remove routes. Customer delivery still goes through entitlement-gated download routes.

Request

GET /api/products/123/files
Authorization: Bearer DEVELOPER_JWT

Response

{
  "files": [
    { "name": "Moonwave-FX.zip", "url": "product-files/..." }
  ]
}

Storefront API

Get storefront

GET /api/storefronts/:slug

Public storefront profile, branding, support details, and developer display data.

Request

GET /api/storefronts/moonwave-fx

Response

{
  "storefront": {
    "slug": "moonwave-fx",
    "displayName": "Moonwave FX",
    "supportEmail": "support@moonwavefx.example"
  }
}

Storefront API

Get storefront products

GET /api/storefronts/:slug/products

Public product cards and checkout eligibility for a developer storefront.

Request

GET /api/storefronts/moonwave-fx/products?limit=24&page=1

Response

{
  "products": [
    {
      "id": 123,
      "title": "Moonwave FX Product",
      "checkoutEligible": true,
      "requiresActivation": true
    }
  ]
}

Checkout

Create product checkout

POST /api/checkout/product

Used by storefront product checkout flows. Subscription-enabled products can return a subscription checkout session while one-time products use payment checkout. Checkout processing is included in SoundSync platform billing.

Request

{
  "productId": 123,
  "saleChannel": "storefront",
  "storefrontSlug": "moonwave-fx",
  "successUrl": "https://example.com/success"
}

Response

{
  "checkoutUrl": "https://checkout.example/...",
  "mode": "subscription",
  "subscriptionCheckout": true,
  "saleChannel": "storefront"
}

Subscriptions API

Read product subscription settings

GET /api/developer/products/:productId/subscription-settings

Developer-authenticated endpoint for reading whether a product has subscription checkout enabled and which lifecycle rules apply.

Request

GET /api/developer/products/123/subscription-settings
Authorization: Bearer DEVELOPER_JWT

Response

{
  "settings": {
    "enabled": true,
    "billingInterval": "monthly",
    "trialDays": 14,
    "failedPaymentGraceDays": 7,
    "cancellationBehavior": "access_until_period_end"
  }
}

Subscriptions API

Update product subscription settings

PUT /api/developer/products/:productId/subscription-settings

Developer-authenticated endpoint for enabling subscription checkout and setting billing interval, trial, failed-payment grace, and cancellation policy.

Request

{
  "enabled": true,
  "billingInterval": "monthly",
  "trialDays": 14,
  "failedPaymentGraceDays": 7,
  "cancellationBehavior": "access_until_period_end"
}

Response

{
  "settings": {
    "enabled": true,
    "billingInterval": "monthly",
    "trialDays": 14,
    "failedPaymentGraceDays": 7,
    "cancellationBehavior": "access_until_period_end"
  }
}

Scheduled deals

List product deals

GET /api/products/:productId/deals

Developer-authenticated route for upcoming, active, canceled, and completed product scheduled deals.

Request

GET /api/products/123/deals
Authorization: Bearer DEVELOPER_JWT

Response

{
  "deals": [
    { "id": "deal_123", "status": "upcoming", "salePrice": 29 }
  ]
}

Scheduled deals

Create, update, or cancel deal

POST/PATCH /api/products/:productId/deals and /api/products/:productId/deals/:dealId/cancel

Create scheduled pricing windows, edit upcoming deals, or cancel a scheduled deal before it should apply.

Request

{
  "name": "Launch sale",
  "salePrice": 29,
  "startsAt": "2026-07-01T14:00:00Z",
  "endsAt": "2026-07-08T14:00:00Z"
}

Response

{
  "deal": {
    "status": "upcoming",
    "salePrice": 29
  }
}

Customer library

Get customer library

GET /api/library

Customer-authenticated route for owned products and delivery file references.

Request

GET /api/library
Authorization: Bearer CUSTOMER_JWT

Response

{
  "products": [
    {
      "entitlement_id": 1001,
      "product_name": "Moonwave FX Product",
      "files": [{ "delivery_url": "/api/delivery/entitlements/1001/files/0" }]
    }
  ]
}

Delivery

Download entitlement file

GET /api/delivery/entitlements/:entitlementId/files/:fileIndex

Protected delivery route. Do not expose raw storage URLs in public UI.

Request

GET /api/delivery/entitlements/1001/files/0

Response

Streams the authorized file or returns an authorization error.

Webhooks

Developer webhooks

GET/POST /api/developer/webhook

Developer-authenticated webhook management. Event coverage continues to expand, so verify required events before building production automation.

Request

POST /api/developer/webhook
Authorization: Bearer DEVELOPER_JWT

{ "url": "https://example.com/soundsync/webhook" }

Response

{
  "id": "webhook_id",
  "secretPreview": "whsec_..."
}

Email Marketing

Campaigns overview

Dashboard Dashboard workflow. Public campaign API documentation is pending.

Dashboard-based campaign workflows handle drafts, eligible audience selection, consent checks, send estimates, and reporting while public API documentation expands as backend contracts are locked.

Request

Use the dashboard Email Marketing Center to create drafts, select eligible audiences, estimate usage, and send controlled campaigns. Public API examples will be added after the campaign contracts are finalized.

Response

{
  "status": "dashboard_workflow",
  "api_docs": "expanding_as_contracts_lock"
}

Email Marketing

Contacts, consent, and suppressions

Dashboard Dashboard workflow. Public audience API documentation is pending.

Marketing sends must target developer-scoped, opted-in, non-suppressed contacts. Purchased, scraped, unsubscribed, bounced, complained, or non-consented contacts must be excluded.

Request

Use dashboard contact and audience tools to manage consent and suppression state. Public audience API examples will be published after the contracts are finalized.

Response

{
  "eligible": true,
  "requires_consent": true,
  "suppression_checked": true
}

Authentication

Developer dashboard APIs use developer JWTs from /api/auth/login and /api/auth/me. Plugin licensing uses product/plugin credentials where required.

Product subscriptions

Subscription products use subscription checkout, lifecycle webhooks, customer entitlements, serial generation, and plugin validation state together.

Error codes

Document invalid, revoked, suspended, deactivated, expired, not-found, product-mismatch, identity-required, and pending verification states in the plugin UI.

Rate limits

Sensitive auth, licensing, checkout, and public marketplace routes have rate limiting. Respect next_check_secs where returned.

Email Marketing docs

Campaign, contacts/audiences, consent fields, unsubscribe/suppression handling, send lifecycle, usage metering, scheduled-deal campaign drafts, and event tracking documentation will expand as public API contracts are finalized.

Testing mode

Use demo products, test checkout, generated plugin credentials, and non-real customer/payment data when validating integrations.

HISE integration

Use product-specific HISE package generation and setup guidance from developer tools, including subscription license model fields and centralized support routing when recurring access is enabled.

JUCE/custom API examples

Use the API examples as implementation guidance. Do not treat a full JUCE SDK as shipped unless the repo includes it.

Security best practices

Keep plugin secrets private where possible, rotate credentials when exposed, avoid raw storage URLs, and lock on confirmed invalid license states.