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
- Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- serialCode: string (required)
- email: string (required)
- firstName: string
- lastName: string
- 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.
- Notes
- Requires a verified signed-in checkout account and uses the current account-owned redemption service. Body email/names do not select or overwrite another customer identity. Use /api/library/redeem-serial for new clients.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"serialCode": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"required": [
"serialCode",
"email"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"serialCode": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/available
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/serials with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
/api/serials/redeemed
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/serials with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
/api/serials/generate
Generate serial inventory for a product.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- product_id: integer (required)
- quantity: integer
- prefix: string
- reseller_id: integer
- new_reseller_name: string
- expires_at: string,null
- promo_price: number
- promo_start: string,null
- promo_expires: string,null
- active_from: string,null
- active_to: string,null
- batch_tag: string
- notes: string
- Returns
- Generated serial batch summary.
- Side effects
- Creates new available serials and can create billable external redemption capacity usage later.
- Notes
- quantity defaults to 1; a supplied prefix must be exactly four alphanumeric characters. Reseller assignment requires an existing relationship.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"product_id": {
"type": "integer",
"minimum": 1
},
"quantity": {
"type": "integer",
"minimum": 1
},
"prefix": {
"type": "string"
},
"reseller_id": {
"type": "integer",
"minimum": 1
},
"new_reseller_name": {
"type": "string"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"promo_price": {
"type": "number"
},
"promo_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"promo_expires": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"active_from": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"active_to": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"batch_tag": {
"type": "string"
},
"notes": {
"type": "string"
}
},
"required": [
"product_id"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"serials": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"customer_email": {
"type": [
"string",
"null"
]
},
"redeemed": {
"type": "boolean"
},
"revoked": {
"type": "boolean"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"redeemed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"download_count": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/import
Import serial inventory from CSV or file upload.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- serials: array (required)
- Returns
- Import summary and validation counts.
- Side effects
- Creates serial records under the developer product catalog.
- Notes
- JSON serial rows, not a file upload. Requires serials.manage, all-products workspace scope and the existing external_serial_import billing-readiness check. Rows missing serialCode, a valid email or productName, or without an owned matching product, are skipped. Existing shared customer names, verification, status and preferences are not overwritten; per-serial name snapshots are retained. A serial and its historical transaction commit together, with any new customer rolled back on a duplicate race or failure. Earlier successful rows remain committed if a later row fails. Historical serials remain billing_eligible:false; this does not import provider payment authority, verify the inbox or override marketing preferences.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"serials": {
"type": "array",
"items": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"productName": {
"type": "string"
},
"serialCode": {
"type": "string"
},
"price": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"downloadCount": {
"type": "integer"
},
"status": {
"type": "string"
},
"redeemDate": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"date": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"required": [
"serials"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"count": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/export
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/serials/export with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
/api/serials/:id
Update a serial record.
- Auth
- Account Bearer session token
- Scope
- serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.
- Request fields
- action: revoke | reassign
- customer_email: string
- Returns
- Updated serial record or status summary.
- Notes
- Requires serials.manage, product ownership and assigned product scope. With no action, updates only an unlinked, unredeemed serial contact email. Changing a linked or redeemed customer identity returns 409 SERIAL_CUSTOMER_IDENTITY_LOCKED; use current customer information controls. reassign clears revocation; it does not redeem or transfer access.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"revoke",
"reassign"
]
},
"customer_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true,
"anyOf": [
{
"required": [
"action"
]
},
{
"required": [
"customer_email"
]
}
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"customer_email": {
"type": [
"string",
"null"
]
},
"redeemed": {
"type": "boolean"
},
"revoked": {
"type": "boolean"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"redeemed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"download_count": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: SERIAL_CUSTOMER_IDENTITY_LOCKED.
/api/serials/revoke/:id
Revoke a serial.
- Auth
- Account Bearer session token
- Scope
- serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.
- Returns
- Updated revoked serial/access state.
- Side effects
- Can remove or block customer access tied to the serial.
- Notes
- Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"customer_email": {
"type": [
"string",
"null"
]
},
"redeemed": {
"type": "boolean"
},
"revoked": {
"type": "boolean"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"redeemed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"download_count": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/reassign/:id
Clear revocation on a legacy serial
- Auth
- Account Bearer session token
- Scope
- serials.manage, owned product and assigned product access. Compatibility restore only; use current developer-scoped controls for new integrations.
- Returns
- The serial row after revoked/revoked_at are cleared.
- Notes
- Despite the legacy name, this handler clears revoked/revoked_at; it does not accept or assign a different customer email. Use current scoped customer-access workflows for identity changes.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"customer_email": {
"type": [
"string",
"null"
]
},
"redeemed": {
"type": "boolean"
},
"revoked": {
"type": "boolean"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"redeemed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"download_count": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/refresh/:id
Reset legacy serial download tracking
- Auth
- Account Bearer session token
- Scope
- serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.
- Returns
- The updated serial row; download_count is reset.
- Side effects
- Resets download tracking and can create a legacy accounting charge. Not a harmless read or activation reset.
- Notes
- Returns the updated serial row after resetting download_count and download logs. Legacy refresh_logs accounting is also written; this is not an activation reset or ordinary validation. Do not use it as a customer self-service device reset or infer current pricing from this legacy route.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"customer_email": {
"type": [
"string",
"null"
]
},
"redeemed": {
"type": "boolean"
},
"revoked": {
"type": "boolean"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"redeemed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"download_count": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/serials/download/:serialId
Serve an authorized serial-linked download.
- Auth
- Account Bearer session token + private token query parameter
- Scope
- Product or storefront scoped
- Request fields
- query token: string (required)
- query file: string (required)
- Returns
- Authorized redirect to short-lived signed R2 delivery.
- Notes
- Requires serial/download context and signed-in owning customer. Only permitted managed files are signed. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Query and header parameters
[
{
"name": "token",
"in": "query",
"schema": {
"type": "string"
},
"required": true,
"description": ""
},
{
"name": "file",
"in": "query",
"schema": {
"type": "string"
},
"required": true,
"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, 503, 401, 403.
Operation errors: CUSTOMER_ACCOUNT_RESTRICTED, CUSTOMER_STORE_CLOSED, SESSION_VERIFICATION_UNAVAILABLE.
/api/serials/download/increment
Check the legacy serial download allowance.
- Auth
- Account Bearer session token
- Scope
- The customer account's owned, redeemed, non-revoked serial and its current product files.
- Request fields
- serial_id: integer (required)
- file_url: string
- Returns
- 200 JSON { allowed: boolean }. This check does not increment the counter.
- Notes
- Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"serial_id": {
"type": "integer",
"minimum": 1
},
"file_url": {
"type": "string"
}
},
"required": [
"serial_id"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"allowed": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 503.
/api/serials/download/confirm
Confirm successful serial download.
- Auth
- Account Bearer session token
- Scope
- The customer account's owned, redeemed, non-revoked serial and its current product files.
- Request fields
- serial_id: integer (required)
- file_url: string (required)
- Returns
- 200 JSON { success: true } after recording download activity.
- Notes
- Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"serial_id": {
"type": "integer",
"minimum": 1
},
"file_url": {
"type": "string"
}
},
"required": [
"serial_id",
"file_url"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 503.
/api/serials/serials/download/confirm
Confirm through the legacy compatibility alias.
- Auth
- Account Bearer session token
- Scope
- The customer account's owned, redeemed, non-revoked serial and its current product files.
- Request fields
- serial_id: integer (required)
- file_url: string (required)
- Returns
- 200 JSON { success: true } after recording download activity.
- Notes
- Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (application/json)
{
"type": "object",
"properties": {
"serial_id": {
"type": "integer",
"minimum": 1
},
"file_url": {
"type": "string"
}
},
"required": [
"serial_id",
"file_url"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 503.
/api/serials/demo-csv
Download a demo CSV template for serial import.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Returns
- CSV template.
- Notes
- Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 500, 503.
/api/serials/transactions
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/purchases with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
/api/serials/customers-list
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/customers with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
/api/serials/resellers
Retired legacy view; use the documented replacement
- Auth
- Account Bearer session token
- Scope
- Retired compatibility response only; no customer, serial or transaction records are queried.
- Returns
- HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.
- Side effects
- None; no data is queried, exported or changed.
- Notes
- This read/export view is retired. Existing filters are ignored. Use /api/developer/partners/resellers with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
No request body fields are read by this operation.
HTTP 410 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "LEGACY_SERIAL_VIEW_RETIRED"
},
"message": {
"type": "string"
},
"documentation": {
"type": "string"
},
"replacement": {
"type": "string"
}
},
"required": [
"code",
"message",
"documentation",
"replacement"
],
"additionalProperties": true
}
Documented failures: 401, 403, 503.
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. |
| Restored | Revocation was cleared by an authorized developer. The legacy reassign action does not change the customer, redeem a serial, or transfer ownership. |
Current delivery versus legacy download helpers
Use the entitlement-delivery and customer-library flows for new integrations. Deprecated serial download counters and confirmation helpers now require a signed-in customer account, an owned active serial, and, for confirmation, a file belonging to its product. They record/check download activity; they do not authorize file access.
Keep customer-account tokens, library/download links, private serial download tokens, and public download codes distinct. Invoice access and review submission require the supported customer-account identity, not an arbitrary shared library link. Follow the authentication and product checks for the actual file request.
SoundSync
Import redeemed serial history from CSV
/api/serials/import-redeemed
Import owned-product redeemed serial rows without editing shared customer profiles
- Auth
- Account Bearer session token
- Scope
- serials.manage and all-products workspace scope; each product name must match a product owned by the effective developer.
- Request fields
- file: string (required). One CSV file with Serial, Product and Email columns; optional legacy serial-history columns are described in the guide.
- Returns
- HTTP 200: success, count.
- Notes
- Legacy redeemed-serial CSV upload, distinct from JSON POST /api/serials/import. Send one multipart file field, not a JSON serials array. Required row values are Serial, Product and a valid Email. Optional columns: First Name, Last Name, Total Price, Purchase Date, Downloads, Revoked, Reseller, Country. Invalid required values, unknown/unowned products and duplicate serials are skipped; count reports inserted serials, not a per-row report. Existing shared customer names, verification, status and marketing preferences are not overwritten. A duplicate race or insert failure rolls back any new customer for that row. Earlier successful rows remain committed if a later row fails with 500 Import failed; do not assume file-level rollback. Imports remain billing_eligible:false and do not establish provider payment, inbox verification or a consent override.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (multipart/form-data)
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "One CSV file with Serial, Product and Email columns; optional legacy serial-history columns are described in the guide."
}
},
"required": [
"file"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"count": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 413, 415, 500, 503.
Operation errors: developer_team_permission_denied, developer_team_all_products_scope_required, UPLOAD_TOO_LARGE, UPLOAD_INVALID, UPLOAD_INCOMPLETE, UNSUPPORTED_FILE_TYPE.
CSV import and JSON import are different requests
POST /api/serials/import-redeemed accepts one multipart file field. The CSV needs Serial, Product and Email columns. Product matches an owned product name case-insensitively. Optional columns are First Name, Last Name, Total Price, Purchase Date, Downloads, Revoked, Reseller and Country. Reseller assignment requires an existing developer relationship.
The response is success:true and count for inserted serials, not a per-row report. Unknown or unowned products, invalid required values and duplicates are skipped. Existing customer identity and marketing preferences remain unchanged; CSV names belong to the serial snapshot. Historical serials stay excluded from redemption billing.
Each successful row commits separately. A duplicate race or insert error rolls back that row and its new customer, not earlier successful rows. A later 500 Import failed therefore does not mean that nothing was imported: inspect serial history before retrying. This upload is distinct from the JSON serials array accepted by POST /api/serials/import. The JSON route also preserves existing shared profiles and commits each serial with its historical transaction; it retains its existing external-import billing-readiness check.
SoundSync
Upload a reviewed historical CSV
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/serials/import-redeemed" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" \
-F "file=@redeemed-serials.csv;type=text/csv"
SoundSync
Legacy available serial CSV import
/api/serials/import-available
Import unredeemed owned-product serial inventory from a legacy CSV
- Auth
- Account Bearer session token
- Scope
- serials.manage and all-products workspace scope; Product must match an owned product name.
- Request fields
- file: string (required)
- Returns
- HTTP 200: success, count.
- Notes
- Required CSV columns: Serial and Product. Optional: Promo Price, Promo Expires, Batch Tag, Active From, Active To, Notes. Unknown/unowned products, missing required values and duplicate codes are skipped. count is inserted inventory, not customer ownership or a per-row report. Inserts commit per row; a later 500 can leave earlier rows imported. Inspect inventory before retrying.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Request (multipart/form-data)
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
},
"additionalProperties": true,
"required": [
"file"
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"count": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 413, 415, 500, 503.
