API Reference
Entitlements API
Verified entitlement concepts and the current public delivery endpoint that authorizes files from active customer entitlements.
SoundSync
Verified endpoints
Only endpoint-backed behavior is documented here.
/api/delivery/entitlements/:entitlementId/files/:fileIndex
Authorizes an active customer entitlement and redirects to short-lived signed R2 delivery.
- Auth
- Account Bearer session token
- Scope
- Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.
- Request fields
- query token: string
- query download_token: string
- query libraryToken: string
- Returns
- 302 redirect to a short-lived signed R2 download URL, or JSON error for missing token, invalid entitlement/file index, inactive entitlement, expansion block, missing file, upstream failure, or delivery failure.
- Side effects
- Logs delivery and updates legacy serial download count when the entitlement metadata includes a serialId.
- Notes
- This endpoint keeps authorization and download accounting in SoundSync while R2 serves the file bytes directly. fileIndex is zero-based. Token ownership, active entitlement, expansion rules and file existence are checked before redirect. Do not persist the storage URL as a permanent download. Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.
Request, response and error reference
Query and header parameters
[
{
"name": "token",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "download_token",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "libraryToken",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 302 response headers
{
"Location": {
"schema": {
"type": "string",
"format": "uri"
},
"description": "Short-lived authorized private download URL."
}
}
Documented failures: 400, 500, 401, 403, 503.
Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED, CUSTOMER_ACCOUNT_RESTRICTED, CUSTOMER_STORE_CLOSED, CUSTOMER_ACCOUNT_REQUIRED.
/api/products/:id/delivery-files
Attach product delivery-file metadata from the developer product setup flow.
- Auth
- Account Bearer session token
- Scope
- Developer-owned product setup.
- Request fields
- url: string (required)
- name: string
- size_gb: number
- Returns
- Product setup response controlled by product setup service.
- Side effects
- May update delivery-file configuration for the product. Not safe for read-only screenshot capture.
- Notes
- Attaches one file; a nested file object is also accepted. href aliases url; size aliases size_gb and is measured in GB. Use completed managed uploads. External delivery URLs must go through Upload by Link; signed, tokenized and raw private-storage URLs are rejected. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"size_gb": {
"type": "number",
"minimum": 0
}
},
"required": [
"url"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"price": {
"type": "number"
},
"salePrice": {
"type": [
"number",
"null"
]
},
"regularPrice": {
"type": "number"
},
"displayPrice": {
"type": "number"
},
"priceDisplay": {
"type": "string"
},
"regularPriceDisplay": {
"type": "string"
},
"salePriceDisplay": {
"type": [
"string",
"null"
]
},
"isOnSale": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"imageUrl": {
"type": [
"string",
"null"
]
},
"coverImage": {
"type": [
"string",
"null"
]
},
"developerId": {
"type": "integer",
"minimum": 1
},
"developerName": {
"type": "string"
},
"developer": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"profileUrl": {
"type": [
"string",
"null"
]
},
"verified": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productType": {
"type": "string"
},
"productTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"subscriptionEnabled": {
"type": "boolean"
},
"billingInterval": {
"type": [
"string",
"null"
]
},
"checkoutEligible": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"requiresActivation": {
"type": "boolean"
},
"supportsSerials": {
"type": "boolean"
},
"supportsDownloads": {
"type": "boolean"
},
"marketplaceAsset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"size_gb": {
"type": "number"
}
},
"additionalProperties": true
}
},
"setupStatus": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"setup_status": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 403, 409, 503.
Operation errors: PRODUCT_FILE_NOT_ACCESSIBLE, PRODUCT_FILE_NOT_VERIFIED, MANAGED_FILE_ATTACHMENT_REQUIRED.
SoundSync
Lifecycle sources
The implementation creates or validates entitlements from these sources.
| Source | Creates or updates entitlement? | Public API surface | Notes |
|---|---|---|---|
| Purchase checkout | Yes | /api/checkout/product and Stripe webhook flows | Checkout/webhook implementation creates order and subscription-linked access; docs here do not expose internal webhook handlers as public customer APIs. |
| Serial activation/redeem | Yes | Licensing and redeem flows | Legacy serial download paths bridge to entitlements when possible. |
| Subscription checkout | Yes | Subscription checkout and Stripe subscription webhooks | Beta-gated; states are documented in Subscriptions API. |
| Partner external order | Yes | /api/partner/v1/orders | Partner API order fulfillment can enqueue order.fulfilled webhooks and create fulfillment material. |
| Manual grant | Implementation-dependent | Developer dashboard, not a verified public endpoint in this pass | Do not publish a manual-grant API until a route-level contract is verified. |
Revocation and refunds
Refund, dispute, subscription expiration, serial revocation, and partner revoke flows can make access inactive. Clients must not assume a stored entitlement remains downloadable; always call the delivery endpoint with a current library token.
One product, more than one way to buy
Offer a one-time purchase, recurring subscription, or both on the same product listing. Each choice has its own saved price, terms and included products; customers select the published choice before checkout. You do not need duplicate listings for these purchase options.
One-time ownership and subscription access can coexist. Effective access combines valid grants: ending one subscription does not erase an independently purchased product or bank. Owning an expansion does not automatically grant its required instrument.
Ownership covers releases of the same product. Software major versions identify technical compatibility, not another paid ownership tier. A separately sold new product still needs its own entitlement.
