API reference
Serials API
Endpoint reference for custom serial integration, customer redemption, serial generation, imports, exports, revocation, reassignment, and serial-linked downloads.
SoundSync
Serial inventory, redemption, and fulfillment calls
These calls cover both customer-facing serial redemption and developer-owned serial operations.
/api/serials/redeem
Redeem a serial from a customer-facing flow.
- Auth
- Public customer route
- Scope
- Product or storefront scoped
- Request fields
- serial/code
- customer email/name where collected
- product or reseller context where supplied
- Returns
- Redemption result, customer/product context, and access/download next step.
- Side effects
- Can mark a serial redeemed and connect it to customer/product access.
/api/serials/available
List available serials for the signed-in developer.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Request fields
- search query
- dateRange filter
- Returns
- Grouped regular and promotion serial inventory by product or batch.
/api/serials/redeemed
List redeemed serials for the signed-in developer.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Request fields
- page
- search
- dateRange
- Returns
- Rows with serial, customer, product, redemption date, status, revenue, and reseller labels.
/api/serials/generate
Generate serial inventory for a product.
- Auth
- Developer account token plus billing readiness
- Scope
- Product or storefront scoped
- Request fields
- product_id/productId
- quantity
- batch or promotion metadata where configured
- Returns
- Generated serial batch summary.
- Side effects
- Creates new available serials and can create billable external redemption capacity usage later.
/api/serials/import
Import serial inventory from CSV or file upload.
- Auth
- Developer account token plus billing readiness
- Scope
- Product or storefront scoped
- Request fields
- Uploaded file or import payload
- product mapping
- batch metadata
- Returns
- Import summary and validation counts.
- Side effects
- Creates serial records under the developer product catalog.
/api/serials/export
Export serials as CSV for the signed-in developer.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Returns
- CSV export of the developer serial inventory.
/api/serials/:id
Update a serial record.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Request fields
- Serial metadata and status fields supported by the API.
- Returns
- Updated serial record or status summary.
/api/serials/revoke/:id
Revoke a serial.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Request fields
- Reason where supplied.
- Returns
- Updated revoked serial/access state.
- Side effects
- Can remove or block customer access tied to the serial.
/api/serials/reassign/:id
Reassign a serial to another customer context.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Request fields
- Target customer/email context and reason where supplied.
- Returns
- Updated serial/customer assignment.
/api/serials/refresh/:id
Refresh download count or delivery accounting for a serial.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Returns
- Updated serial download counter state.
/api/serials/download/:serialId
Serve an authorized serial-linked download.
- Auth
- Download authorization context
- Scope
- Product or storefront scoped
- Request fields
- serialId path parameter plus request authorization context.
- Returns
- Authorized redirect to short-lived signed R2 delivery.
/api/serials/download/increment
Increment serial download count.
- Auth
- Download/customer flow context
- Scope
- Product or storefront scoped
- Request fields
- serialId or serial context
- file/download context
- Returns
- Updated counter state.
/api/serials/download/confirm
Confirm successful serial download.
- Auth
- Download/customer flow context
- Scope
- Product or storefront scoped
- Request fields
- serialId or serial context
- file/download context
- Returns
- Download confirmation result.
/api/serials/serials/download/confirm
Confirm download from a customer-token flow.
- Auth
- Customer token
- Scope
- Product or storefront scoped
- Request fields
- Customer token plus serial/download context.
- Returns
- Download confirmation result.
/api/serials/demo-csv
Download a demo CSV template for serial import.
- Auth
- Public utility route
- Scope
- Product or storefront scoped
- Returns
- CSV template.
/api/serials/transactions
List serial-related transactions.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Returns
- Transaction rows for serial/customer/product activity.
/api/serials/customers-list
List customers for serial assignment and filtering.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Returns
- Developer-scoped customer list.
/api/serials/resellers
List reseller/partner labels for serial workflows.
- Auth
- Developer account token
- Scope
- Product or storefront scoped
- Returns
- Developer-scoped reseller relationship list.
SoundSync
Serial state model
Serials can support direct sales, external/partner sales, HISE serial activation, and customer library access.
| State | Meaning |
|---|---|
| Available | Serial exists and has not been redeemed. |
| Redeemed | Serial has been connected to a customer/product context. |
| Revoked | Serial should no longer authorize access. |
| Reassigned | Ownership/customer assignment was changed by an authorized developer action. |