Guide
Current API Operation Map
Recently added package, upload, WooCommerce, partner, marketing, promotion, tracking, customer, and installment routes.
Use the right level of reference
This operation map supplements the detailed endpoint guides. Open each operation for its reviewed fields or transport contract, authentication, errors and conditional behavior. Source review is not seeded response testing of every provider outcome. Read the linked workflow before implementing a request.
Product credentials, developer sessions, customer sessions, partner Bearer keys, and provider webhook signatures are distinct. Owner-only administration and payment-provider callbacks are not public plugin SDK methods.
SoundSync
Customer marketplace discovery
Public catalog endpoints expose customer-facing publication/discovery data, not developer account records.
/api/marketplace/homepage
Customer homepage content
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: hero, sections, generatedAt, cacheKey, sectionOrdering, viewer.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"hero": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"sections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"status": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"title": {
"type": "string"
},
"href": {
"type": "string"
},
"source": {
"type": "string"
},
"priority": {
"type": "number"
}
},
"additionalProperties": true
}
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cacheKey": {
"type": "string"
},
"sectionOrdering": {
"type": "array",
"items": {
"type": "string"
}
},
"viewer": {
"type": "object",
"properties": {
"authenticated": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/deals
Published deals
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: products, pagination, generatedAt, sort.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sort": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/new-releases
Recent published releases
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: products, pagination, generatedAt.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/free
Supported free-product discovery
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: products, pagination, generatedAt.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/developers
Customer developer directory
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: developers, pagination.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"developers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"shortBio": {
"type": "string"
}
},
"additionalProperties": true
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/collections
Published collections
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: collections, pagination, generatedAt.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"collections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"productCount": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/collections/:slug
Collection detail
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: collection, products, pagination, generatedAt.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"collection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"productCount": {
"type": "integer"
}
},
"additionalProperties": true
},
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/categories/:slug
Category discovery
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: category, products, pagination, generatedAt.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"category": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/marketplace/search
Customer product search
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query q: string (required)
- query page: integer
- query limit: integer
- query search: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- HTTP 200: products, pagination, generatedAt, q, developers.
- Notes
- An empty q returns 400 SEARCH_QUERY_REQUIRED.
Request, response and error reference
Query and header parameters
[
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": true,
"description": ""
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"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
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"q": {
"type": "string"
},
"developers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"shortBio": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
SoundSync
Marketplace placement assets
Authenticated developer with product access; mutations require product edit permission. Uploads follow guarded image limits and approved publishing state.
/api/developer/products/:productId/marketplace-assets
Asset builder overview
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: productId, developerId, sourceAssetTypes, usageRoles, primaryRoles, presentationModes, placements, profile, assets, masks, duplicateGroups, generatedAssets, generatedAssetVersions, templates, readiness.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/preview
Private placement preview
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query placementType: string
- query selectedAssetId: integer
- Returns
- HTTP 200: preview, private, product, developer, selectedPlacement, selectedAssetId, assets, primaryAsset, generatedAssets, generatedAssetVersions, placements, profile, privatePreviewNotice.
- Notes
- Private preview does not publish a product, reserve a marketplace placement or activate artwork.
Request, response and error reference
Query and header parameters
[
{
"name": "placementType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "selectedAssetId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"preview": {
"type": "boolean"
},
"private": {
"type": "boolean"
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
},
"developer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
},
"selectedPlacement": {
"type": "string"
},
"selectedAssetId": {
"type": [
"integer",
"null"
]
},
"assets": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"primaryAsset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"privatePreviewNotice": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/preview/:placementType
One private placement preview
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query selectedAssetId: integer
- Returns
- HTTP 200: asset, preview, private.
Request, response and error reference
Query and header parameters
[
{
"name": "selectedAssetId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"preview": {
"type": "boolean"
},
"private": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/organize
Organize source assets
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 201: productId, developerId, sourceAssetTypes, usageRoles, primaryRoles, presentationModes, placements, profile, assets, masks, duplicateGroups, generatedAssets, generatedAssetVersions, templates, readiness.
- Notes
- Organizes existing product assets; this can update source-asset records.
Request, response and error reference
No request body fields are read by this operation.
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/source-assets
Upload guarded source images
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- files: array (required)
- sourceClassification: string
- usageRoles: string
- primaryRole: string
- autoGenerate: string
- Returns
- HTTP 201: assets, autoGeneration, overview.
- Notes
- Use repeated files fields (at most 12). autoGenerate is the multipart string true to request generation; upload success and generation success are separate.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"files": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"items": {
"type": "string",
"format": "binary"
}
},
"sourceClassification": {
"type": "string"
},
"usageRoles": {
"type": "string"
},
"primaryRole": {
"type": "string"
},
"autoGenerate": {
"type": "string"
}
},
"required": [
"files"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"autoGeneration": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/source-assets/:assetId
Update source metadata
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- sourceClassification: string
- classificationConfidence: string
- classificationReason: string
- usageRoles: array
- primaryRole: string
- archived: boolean
- reviewStatus: string
- developerConfirmedClassification: boolean
- Returns
- HTTP 200: asset, overview, autoGeneration.
- Notes
- Updating source roles can queue core marketplace artwork. This is not only a label change.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"classificationReason": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"reviewStatus": {
"type": "string"
},
"developerConfirmedClassification": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"autoGeneration": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/source-assets/:assetId/extraction
Request product-interface extraction
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 201: mask, derivativeAsset, fallbackRecommendation.
Request, response and error reference
No request body fields are read by this operation.
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"mask": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
},
"derivativeAsset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"fallbackRecommendation": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/masks/:maskId
Save mask correction
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- crop: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- brushOperations: array
- threshold: number
- edgeFeather: number
- approvalState: string
- Returns
- HTTP 200: mask, derivativeAsset.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"brushOperations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
},
"approvalState": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"mask": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
},
"derivativeAsset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/profile
Update placement profile
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- presentationMode: string
- visualDirection: string
- palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- selectedTemplateId: string
- subjectAssetId: integer
- settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: profile, overview.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/templates
List supported templates
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query includeInactive: boolean
- Returns
- HTTP 200: templates.
Request, response and error reference
Query and header parameters
[
{
"name": "includeInactive",
"in": "query",
"schema": {
"type": "boolean"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"family": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/render-jobs
Queue a render or placement family
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- placementType: string
- placements: array
- presentationMode: string
- templateId: string
- subjectAssetId: integer
- sourceAssetId: integer
- profilePatch: object
- palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- idempotencyKey: string
- processSynchronously: boolean
- coreSet: boolean
- force: boolean
- autoSelectTemplate: boolean
- organizeExistingMedia: boolean
- Returns
- HTTP 202: job, jobs, assets.
- Notes
- placements requests a family; a single placement creates one job. Inspect the job outcome; accepted is not published.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"placementType": {
"type": "string"
},
"placements": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationMode": {
"type": "string"
},
"templateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"profilePatch": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"idempotencyKey": {
"type": "string"
},
"processSynchronously": {
"type": "boolean"
},
"coreSet": {
"type": "boolean"
},
"force": {
"type": "boolean"
},
"autoSelectTemplate": {
"type": "boolean"
},
"organizeExistingMedia": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"placementType": {
"type": "string"
},
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"errorCode": {
"type": [
"string",
"null"
]
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"placementType": {
"type": "string"
},
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"errorCode": {
"type": [
"string",
"null"
]
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/ensure-core-set
Prepare the supported core placements
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- placementType: string
- placements: array
- presentationMode: string
- templateId: string
- subjectAssetId: integer
- sourceAssetId: integer
- profilePatch: object
- palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- idempotencyKey: string
- processSynchronously: boolean
- coreSet: boolean
- force: boolean
- autoSelectTemplate: boolean
- organizeExistingMedia: boolean
- Returns
- HTTP 202: ready, sourceAsset, generated, jobs, placements, skippedPlacements, overview.
- Notes
- Prepares missing core placements and normally preserves active assets. force:true deliberately regenerates the requested set. sourceAssetId (or subjectAssetId) selects an owned usable source; an explicitly unavailable selection returns SOURCE_ASSET_REQUIRED rather than silently using a different upload. Without a usable source, MARKETPLACE_SOURCE_REQUIRED leaves the saved product unchanged. Core rendering resolves a compatible mode per placement: background_texture uses minimal_brand; other incompatible modes use a supported source-based recommendation. A single non-core incompatible render can return PLACEMENT_MODE_INCOMPATIBLE. Inspect generated[], jobs[], skippedPlacements and overview; this does not guarantee marketplace placement or publish the product.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"placementType": {
"type": "string"
},
"placements": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationMode": {
"type": "string"
},
"templateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"profilePatch": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"idempotencyKey": {
"type": "string"
},
"processSynchronously": {
"type": "boolean"
},
"coreSet": {
"type": "boolean"
},
"force": {
"type": "boolean"
},
"autoSelectTemplate": {
"type": "boolean"
},
"organizeExistingMedia": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"ready": {
"type": "boolean"
},
"sourceAsset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"generated": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"placementType": {
"type": "string"
},
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"errorCode": {
"type": [
"string",
"null"
]
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"placements": {
"type": "array",
"items": {
"type": "string"
}
},
"skippedPlacements": {
"type": "array",
"items": {
"type": "string"
}
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/render-jobs/:jobId
Inspect render progress/result
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"placementType": {
"type": "string"
},
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"errorCode": {
"type": [
"string",
"null"
]
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId/approval
Change approval deliberately
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- status: string
- approvalStatus: string
- reason: string
- Returns
- HTTP 200: asset, overview, autoGeneration.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"approvalStatus": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"autoGeneration": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId/restore
Restore a generated asset
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- reason: string
- Returns
- HTTP 200: asset, overview, autoGeneration.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"autoGeneration": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId
Delete the selected generated asset
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- preserveCurrent: boolean
- preserveActive: boolean
- permanent: boolean
- forcePermanent: boolean
- strictStorageDelete: boolean
- Returns
- HTTP 200: deleted, archived, skipped, preservedCurrent, assetId, asset, reason, storageDeleted, overview.
- Notes
- Default removal can archive rather than physically delete. Current artwork can be preserved. Inspect deleted, archived and storageDeleted separately.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"preserveCurrent": {
"type": "boolean"
},
"preserveActive": {
"type": "boolean"
},
"permanent": {
"type": "boolean"
},
"forcePermanent": {
"type": "boolean"
},
"strictStorageDelete": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
},
"skipped": {
"type": "boolean"
},
"preservedCurrent": {
"type": "boolean"
},
"assetId": {
"type": "integer",
"minimum": 1
},
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"reason": {
"type": "string"
},
"storageDeleted": {
"type": "boolean"
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/replacements/:placementType
Upload one custom replacement
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- file: string (required)
- active: string
- altText: string
- creatorType: string
- Returns
- HTTP 201: asset, overview, autoGeneration.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"active": {
"type": "string"
},
"altText": {
"type": "string"
},
"creatorType": {
"type": "string"
}
},
"required": [
"file"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"overview": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"sourceAssetTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationModes": {
"type": "array",
"items": {
"type": "string"
}
},
"placements": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"profile": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"approvalState": {
"type": "string"
},
"crop": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"threshold": {
"type": "number"
},
"edgeFeather": {
"type": "number"
}
},
"additionalProperties": true
}
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"generatedAssets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"generatedAssetVersions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"templates": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"readiness": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"autoGeneration": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/marketplace-assets/ensure/:placementType
Prepare a particular placement
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- placementType: string
- placements: array
- presentationMode: string
- templateId: string
- subjectAssetId: integer
- sourceAssetId: integer
- profilePatch: object
- palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- idempotencyKey: string
- processSynchronously: boolean
- coreSet: boolean
- force: boolean
- autoSelectTemplate: boolean
- organizeExistingMedia: boolean
- Returns
- HTTP 202: job, asset, created.
- Notes
- May reuse a valid asset or prepare a job. Do not infer a new render from every successful ensure call.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"placementType": {
"type": "string"
},
"placements": {
"type": "array",
"items": {
"type": "string"
}
},
"presentationMode": {
"type": "string"
},
"templateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"profilePatch": {
"type": "object",
"properties": {
"presentationMode": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"selectedTemplateId": {
"type": "string"
},
"subjectAssetId": {
"type": "integer",
"minimum": 1
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"idempotencyKey": {
"type": "string"
},
"processSynchronously": {
"type": "boolean"
},
"coreSet": {
"type": "boolean"
},
"force": {
"type": "boolean"
},
"autoSelectTemplate": {
"type": "boolean"
},
"organizeExistingMedia": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"placementType": {
"type": "string"
},
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"errorCode": {
"type": [
"string",
"null"
]
},
"errorMessage": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"asset": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"placementType": {
"type": "string"
},
"assetType": {
"type": "string"
},
"active": {
"type": "boolean"
},
"approvalStatus": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"sourceClassification": {
"type": "string"
},
"classificationConfidence": {
"type": "string"
},
"usageRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryRole": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
},
"additionalProperties": true
},
"created": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
SoundSync
Subscription bundle additions
Authenticated customer; ownership, provider state, and explicit billing authorization are checked by the supported service path.
/api/subscriptions/bundles/cancel-scheduled-change
Cancel an eligible pending plan change
- Auth
- Account Bearer session token
- Scope
- The signed-in buyer's subscription and authorized provider billing relationship.
- Request fields
- bundleSubscriptionId: integer (required)
- Returns
- HTTP 200: canceled, changeId, subscriptionId.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"bundleSubscriptionId": {
"type": "integer",
"minimum": 1
}
},
"required": [
"bundleSubscriptionId"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"canceled": {
"type": "boolean"
},
"changeId": {
"type": "integer",
"minimum": 1
},
"subscriptionId": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409, 503.
/api/subscriptions/bundles/billing-portal
Open the permitted provider billing portal
- Auth
- Account Bearer session token
- Scope
- The signed-in buyer's subscription and authorized provider billing relationship.
- Request fields
- bundleSubscriptionId: integer
- standaloneSubscriptionId: integer
- historyOnly: boolean
- Returns
- HTTP 200: url, sessionId, expiresAt.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"bundleSubscriptionId": {
"type": "integer",
"minimum": 1
},
"standaloneSubscriptionId": {
"type": "integer",
"minimum": 1
},
"historyOnly": {
"type": "boolean"
}
},
"additionalProperties": true,
"oneOf": [
{
"required": [
"bundleSubscriptionId"
],
"not": {
"required": [
"standaloneSubscriptionId"
]
}
},
{
"required": [
"standaloneSubscriptionId"
],
"not": {
"required": [
"bundleSubscriptionId"
]
}
}
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"sessionId": {
"type": "string"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409, 503.
/api/subscriptions/bundles/manual-billing-setup
Start customer-authorized billing setup for a manual grant
- Auth
- Account Bearer session token
- Scope
- The signed-in buyer's subscription and authorized provider billing relationship.
- Request fields
- kind: bundle | standalone (required)
- subscriptionId: integer (required)
- sessionId: string
- expectedTotalCents: integer
- Returns
- HTTP 201: url, sessionId.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"kind": {
"enum": [
"bundle",
"standalone"
]
},
"subscriptionId": {
"type": "integer",
"minimum": 1
},
"sessionId": {
"type": "string"
},
"expectedTotalCents": {
"type": "integer",
"minimum": 0
}
},
"required": [
"kind",
"subscriptionId"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"sessionId": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409, 503.
/api/subscriptions/bundles/manual-billing-preview
Preview the proposed billing conversion
- Auth
- Account Bearer session token
- Scope
- The signed-in buyer's subscription and authorized provider billing relationship.
- Request fields
- kind: bundle | standalone (required)
- subscriptionId: integer (required)
- sessionId: string (required)
- expectedTotalCents: integer
- Returns
- HTTP 200: success, amountCents, taxAmountCents, totalCents, currency, productName, sessionId, subscriptionId, kind.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"kind": {
"enum": [
"bundle",
"standalone"
]
},
"subscriptionId": {
"type": "integer",
"minimum": 1
},
"sessionId": {
"type": "string"
},
"expectedTotalCents": {
"type": "integer",
"minimum": 0
}
},
"required": [
"kind",
"subscriptionId",
"sessionId"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"amountCents": {
"type": "integer",
"minimum": 0
},
"taxAmountCents": {
"type": "integer",
"minimum": 0
},
"totalCents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"productName": {
"type": "string"
},
"sessionId": {
"type": "string"
},
"subscriptionId": {
"type": "integer",
"minimum": 1
},
"kind": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409, 503.
/api/subscriptions/bundles/manual-billing-confirm
Confirm the supported billing setup
- Auth
- Account Bearer session token
- Scope
- The signed-in buyer's subscription and authorized provider billing relationship.
- Request fields
- kind: bundle | standalone (required)
- subscriptionId: integer (required)
- sessionId: string (required)
- expectedTotalCents: integer (required)
- Returns
- HTTP 200: success, amountCents, taxAmountCents, totalCents, currency, productName, sessionId, subscriptionId, kind.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"kind": {
"enum": [
"bundle",
"standalone"
]
},
"subscriptionId": {
"type": "integer",
"minimum": 1
},
"sessionId": {
"type": "string"
},
"expectedTotalCents": {
"type": "integer",
"minimum": 0
}
},
"required": [
"kind",
"subscriptionId",
"sessionId",
"expectedTotalCents"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"amountCents": {
"type": "integer",
"minimum": 0
},
"taxAmountCents": {
"type": "integer",
"minimum": 0
},
"totalCents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"productName": {
"type": "string"
},
"sessionId": {
"type": "string"
},
"subscriptionId": {
"type": "integer",
"minimum": 1
},
"kind": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409, 503.
SoundSync
Product packages
Authenticated developer with the required product access. Never distribute the account token in the package.
/api/developer/products/:productId/juce-package
Prepare the product source package and return a private download link
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- query platform: value
- query releaseChannel: value
- Returns
- HTTP 200: url, filename, expiresIn.
- Notes
- Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.
Request, response and error reference
Query and header parameters
[
{
"name": "platform",
"in": "query",
"required": false,
"schema": {
"enum": [
"windows",
"macos"
]
}
},
{
"name": "releaseChannel",
"in": "query",
"required": false,
"schema": {
"const": "stable"
}
}
]
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"filename": {
"type": "string"
},
"expiresIn": {
"const": 300
}
},
"required": [
"url",
"filename",
"expiresIn"
],
"additionalProperties": true
}
Documented failures: 503.
/api/developer/products/:productId/juce-package/download
Download the product package
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- query platform: value
- query releaseChannel: value
- Returns
- HTTP 200: url, filename, expiresIn.
- Notes
- Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.
Request, response and error reference
Query and header parameters
[
{
"name": "platform",
"in": "query",
"required": false,
"schema": {
"enum": [
"windows",
"macos"
]
}
},
{
"name": "releaseChannel",
"in": "query",
"required": false,
"schema": {
"const": "stable"
}
}
]
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"filename": {
"type": "string"
},
"expiresIn": {
"const": 300
}
},
"required": [
"url",
"filename",
"expiresIn"
],
"additionalProperties": true
}
Documented failures: 503.
/api/developer/products/:productId/juce-package/generate
Generate the product-specific package
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- platform: windows | macos
- releaseChannel: "stable"
- Returns
- HTTP 200: url, filename, expiresIn.
- Notes
- Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"platform": {
"enum": [
"windows",
"macos"
]
},
"releaseChannel": {
"const": "stable"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"filename": {
"type": "string"
},
"expiresIn": {
"const": 300
}
},
"required": [
"url",
"filename",
"expiresIn"
],
"additionalProperties": true
}
Documented failures: 503.
SoundSync
Private product uploads
Authenticated developer; the service verifies product ownership/permissions. A signed upload URL is temporary, private authorization.
/api/products/:id/files/direct-uploads
Start a direct upload; return job and signed PUT instructions
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- filename: string (required)
- sizeBytes: integer (required)
- mimeType: string
- multipart: boolean
- fileFingerprint: string
- Returns
- HTTP 201: job, upload, processing, deduplicated, file, product.
- Notes
- Use returned upload instructions. Local multipart resume requires reselecting the identical file within the returned deadline; the browser cannot reopen it silently. 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": {
"filename": {
"type": "string"
},
"sizeBytes": {
"type": "integer",
"minimum": 1,
"maximum": 10000000000
},
"mimeType": {
"type": "string"
},
"multipart": {
"type": "boolean"
},
"fileFingerprint": {
"type": "string",
"pattern": "^v1:[a-f0-9]{64}$"
}
},
"required": [
"filename",
"sizeBytes"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/direct-uploads/:jobId/complete
Verify stored size and session, then attach the file
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- sizeBytes: integer
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
- Notes
- Completes only after object/session/size verification. Do not manually attach an unfinished storage key. 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": {
"sizeBytes": {
"type": "integer"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/chunk-sessions
Start a local chunk session
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- filename: string (required)
- mimeType: string
- size: integer (required)
- totalChunks: integer (required)
- Returns
- HTTP 201: upload.
- Notes
- 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": {
"filename": {
"type": "string"
},
"mimeType": {
"type": "string"
},
"size": {
"type": "integer"
},
"totalChunks": {
"type": "integer",
"minimum": 1
}
},
"required": [
"filename",
"size",
"totalChunks"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"upload": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"filename": {
"type": "string"
},
"totalSize": {
"type": "integer"
},
"totalChunks": {
"type": "integer"
},
"chunkSize": {
"type": "integer"
},
"maxChunkSize": {
"type": "integer"
},
"receivedBytes": {
"type": "integer"
},
"progress": {
"type": "number"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/chunk-sessions/:uploadId/chunks
Upload a multipart chunk
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- index: integer (required)
- chunk: string (required)
- Returns
- HTTP 200: upload.
- Notes
- Upload the chunk file under the chunk field. index is zero-based; validate returned completion rather than assuming arrival order. 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 (multipart/form-data)
{
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"chunk": {
"type": "string",
"format": "binary"
}
},
"required": [
"index",
"chunk"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"upload": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"filename": {
"type": "string"
},
"totalSize": {
"type": "integer"
},
"totalChunks": {
"type": "integer"
},
"receivedBytes": {
"type": "integer"
},
"progress": {
"type": "number"
},
"complete": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/chunk-sessions/:uploadId/complete
Complete chunk assembly
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
- Notes
- Missing or mismatched chunks fail verification; processing can continue asynchronously after assembly. 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
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/upload-link
Prepare a permitted remote upload
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- url: string (required)
- Returns
- HTTP 202: job, upload, processing, deduplicated, file, product.
- Notes
- Imports an authorized direct link into private storage. A pending job is not a deliverable file; protected/expired links need a fresh direct source. 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"
}
},
"required": [
"url"
],
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/:jobId
Read job state
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
- Notes
- 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
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/:jobId/retry
Retry supported failed work
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
- Notes
- A remote retry may restart from the source; do not promise byte-level resume. 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
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/uploads/:jobId/cancel
Cancel the upload job
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
- Notes
- 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
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/products/:id/files/:fileId/download
Authorized developer file download
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: url, expiresIn.
- Notes
- Developer-authorized private file preview/download metadata, not a public URL or customer entitlement grant. 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
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
SoundSync
WooCommerce mapping review
Authenticated developer with approved relationship/product permissions. These are developer controls, not storefront calls.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores
List related store connections
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope.
- Returns
- HTTP 200: connections.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"connections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"relationship_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"environment": {
"type": "string"
},
"display_name": {
"type": "string"
},
"base_url": {
"type": "string"
},
"status": {
"type": "string"
},
"connected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"activated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_catalog_sync_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_webhook_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_error_code": {
"type": [
"string",
"null"
]
},
"last_error_message": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId
Inspect connection and catalog review
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query status: string
- Returns
- HTTP 200: connection, catalog, products, total, offset.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"connection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"relationship_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"environment": {
"type": "string"
},
"display_name": {
"type": "string"
},
"base_url": {
"type": "string"
},
"status": {
"type": "string"
},
"connected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"activated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_catalog_sync_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_webhook_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_error_code": {
"type": [
"string",
"null"
]
},
"last_error_message": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"catalog": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"products": {
"type": "array",
"items": {
"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
}
},
"total": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/mappings
Approve/update a product mapping
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope. Also requires partners.manage.
- Request fields
- targets: array (required)
- requireExact: boolean
- all_variations: boolean
- Returns
- HTTP 200: mapped, revision, target_count.
- Notes
- Targets must be distinct approved API-fulfillment products. Revenue allocations total 10000 basis points; exact-only confirmation rejects candidates needing individual review.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"soundsync_product_id": {
"type": "integer",
"minimum": 1
},
"component_quantity": {
"type": "integer",
"minimum": 1
},
"revenue_allocation_bps": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"requireExact": {
"type": "boolean"
},
"all_variations": {
"type": "boolean"
}
},
"required": [
"targets"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"mapped": {
"type": "boolean"
},
"revision": {
"type": "integer"
},
"target_count": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/mappings
Remove a mapping
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope. Also requires partners.manage.
- Returns
- HTTP 200: catalog_item_id, removed.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"catalog_item_id": {
"type": "integer",
"minimum": 1
},
"removed": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/suggestion
Review the suggested mapping
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope. Also requires partners.manage.
- Request fields
- dismissed: boolean (required)
- Returns
- HTTP 200: catalog_item_id, suggestion_dismissed.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"dismissed": {
"type": "boolean"
}
},
"required": [
"dismissed"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"catalog_item_id": {
"type": "integer",
"minimum": 1
},
"suggestion_dismissed": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/confirm-exact-mappings
Confirm the supported exact-match review
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope. Also requires partners.manage.
- Returns
- HTTP 200: mapped, failures.
- Notes
- Bulk-confirms only exact eligible suggestions. Inspect failures; this does not approve ambiguous matches.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"mapped": {
"type": "integer"
},
"failures": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/activate
Activate the reviewed connection
- Auth
- Account Bearer session token
- Scope
- partners.view and all-products workspace scope. Also requires partners.manage.
- Returns
- HTTP 200: connection.
- Notes
- Requires active relationship/API permission, authorized/synced store, complete confirmed mappings and healthy webhooks. Does not make SoundSync the seller of externally collected payments.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"connection": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"relationship_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"environment": {
"type": "string"
},
"display_name": {
"type": "string"
},
"base_url": {
"type": "string"
},
"status": {
"type": "string"
},
"connected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"activated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_catalog_sync_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_webhook_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_error_code": {
"type": [
"string",
"null"
]
},
"last_error_message": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
SoundSync
Partner API additions
Approved partner Bearer credentials with the required scopes. Keep them server-side; use Idempotency-Key for supported external-order creation.
/api/partner/v1/serial-pools
Scoped pool inventory; serial_pools:read
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query product_id: integer
- Returns
- HTTP 200: serial_pools, pools.
Request, response and error reference
Query and header parameters
[
{
"name": "product_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1
}
}
]
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"serial_pools": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"pools": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
/api/partner/v1/serial-pools/:poolId
Scoped pool detail; serial_pools:read
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: serial_pool, pool, items.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"serial_pool": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"pool": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"serial_code": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
/api/partner/v1/sales
External order creation using the orders/sales contract
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- header Idempotency-Key: string (required)
- external_order_id: string
- externalOrderId: string
- customer_email: string
- customerEmail: string
- purchased_at: string
- purchasedAt: string
- items: array (required)
- Returns
- HTTP 201: success, soundsync_order_id, external_order_id, relationship_id, source, label, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, test_mode, would_fulfill, customer, items.
- Notes
- Custom fulfillment requires SoundSync activation. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED without issuing access. Test credentials normally validate only: test_mode:true and would_fulfill:true are not actual fulfillment; inspect fulfillment_event_created and item statuses. Real test fulfillment requires its separate enabled capability. External processing fees are not covered by SoundSync.
Request, response and error reference
Query and header parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": ""
}
]
Request (application/json)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.soundsync.dev/contracts/partner-api.schema.json",
"title": "Partner external order",
"type": "object",
"properties": {
"external_order_id": {
"type": "string"
},
"externalOrderId": {
"type": "string"
},
"customer_email": {
"type": "string",
"format": "email"
},
"customerEmail": {
"type": "string",
"format": "email"
},
"purchased_at": {
"type": "string",
"format": "date-time"
},
"purchasedAt": {
"type": "string",
"format": "date-time"
},
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"reseller_sku": {
"type": "string",
"minLength": 1
},
"resellerSku": {
"type": "string",
"minLength": 1
},
"sku": {
"type": "string",
"minLength": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"unit_reported_price_cents": {
"type": "integer",
"minimum": 0
}
},
"anyOf": [
{
"required": [
"product_id"
]
},
{
"required": [
"productId"
]
},
{
"required": [
"reseller_sku"
]
},
{
"required": [
"resellerSku"
]
},
{
"required": [
"sku"
]
}
]
}
}
},
"allOf": [
{
"anyOf": [
{
"required": [
"external_order_id"
]
},
{
"required": [
"externalOrderId"
]
}
]
},
{
"anyOf": [
{
"required": [
"customer_email"
]
},
{
"required": [
"customerEmail"
]
}
]
},
{
"anyOf": [
{
"required": [
"purchased_at"
]
},
{
"required": [
"purchasedAt"
]
}
]
}
],
"required": [
"items"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"soundsync_order_id": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"relationship_id": {
"type": "string"
},
"source": {
"type": "string"
},
"label": {
"type": "string"
},
"financial_classification": {
"type": "string"
},
"soundsync_checkout_fee_cents": {
"type": "integer",
"minimum": 0
},
"reported_total_paid_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"verification_status": {
"type": "string"
},
"fulfillment_event_created": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"duplicate_external_order": {
"type": "boolean"
},
"test_mode": {
"type": "boolean"
},
"would_fulfill": {
"type": "boolean"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"type": "string"
},
"license": {
"type": [
"object",
"null"
],
"properties": {
"serial": {
"type": "string"
},
"status": {
"type": "string"
},
"redemption_status": {
"type": "string"
}
},
"additionalProperties": true,
"description": "Private serial access when issued; null for validation-only test results."
},
"entitlement": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"claim_url": {
"type": [
"string",
"null"
],
"description": "Private customer claim URL when issued; never log or publish it."
},
"commercial_model": {
"type": "string"
},
"wholesale_rate_cents": {
"type": "integer",
"minimum": 0
},
"commission_rate_bps": {
"type": "integer",
"minimum": 0
},
"developer_revenue_share_bps": {
"type": "integer",
"minimum": 0
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/sales/:externalOrderId
Lookup the reported sale
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: success, soundsync_order_id, external_order_id, relationship_id, source, label, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, test_mode, would_fulfill, customer, items.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"soundsync_order_id": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"relationship_id": {
"type": "string"
},
"source": {
"type": "string"
},
"label": {
"type": "string"
},
"financial_classification": {
"type": "string"
},
"soundsync_checkout_fee_cents": {
"type": "integer",
"minimum": 0
},
"reported_total_paid_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"verification_status": {
"type": "string"
},
"fulfillment_event_created": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"duplicate_external_order": {
"type": "boolean"
},
"test_mode": {
"type": "boolean"
},
"would_fulfill": {
"type": "boolean"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"type": "string"
},
"license": {
"type": [
"object",
"null"
],
"properties": {
"serial": {
"type": "string"
},
"status": {
"type": "string"
},
"redemption_status": {
"type": "string"
}
},
"additionalProperties": true,
"description": "Private serial access when issued; null for validation-only test results."
},
"entitlement": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"claim_url": {
"type": [
"string",
"null"
],
"description": "Private customer claim URL when issued; never log or publish it."
},
"commercial_model": {
"type": "string"
},
"wholesale_rate_cents": {
"type": "integer",
"minimum": 0
},
"commission_rate_bps": {
"type": "integer",
"minimum": 0
},
"developer_revenue_share_bps": {
"type": "integer",
"minimum": 0
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
/api/partner/v1/sales/:externalOrderId/refund
Report the supported external refund
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- reason: string
- Returns
- HTTP 200: status, code, external_order_id, idempotent_replay.
- Notes
- Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"code": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"idempotent_replay": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/sales/:externalOrderId/revoke
Revoke under the approved external-access contract
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- reason: string
- Returns
- HTTP 200: status, code, external_order_id, idempotent_replay.
- Notes
- Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"code": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"idempotent_replay": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/deals
Scoped deal listing
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: campaigns, deals.
- Notes
- Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"start_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"end_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": "string"
},
"approved_sale_price_cents": {
"type": "integer",
"minimum": 0
},
"commercial_model": {
"type": "string"
},
"license_cap": {
"type": "integer"
},
"issued_count": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"deals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"start_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"end_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": "string"
},
"approved_sale_price_cents": {
"type": "integer",
"minimum": 0
},
"commercial_model": {
"type": "string"
},
"license_cap": {
"type": "integer"
},
"issued_count": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/partner/v1/deals/:dealId
Scoped deal detail
- Auth
- Relationship-scoped partner API key
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: campaign, deal.
- Notes
- Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"start_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"end_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": "string"
},
"approved_sale_price_cents": {
"type": "integer",
"minimum": 0
},
"commercial_model": {
"type": "string"
},
"license_cap": {
"type": "integer"
},
"issued_count": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"start_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"end_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"reseller_sku": {
"type": "string"
},
"approved_sale_price_cents": {
"type": "integer",
"minimum": 0
},
"commercial_model": {
"type": "string"
},
"license_cap": {
"type": "integer"
},
"issued_count": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
SoundSync
Marketing additions
Authenticated developer marketing permissions and product/audience scope. Sending remains subject to consent, suppression, configuration, and provider readiness.
/api/developer/marketing/segments
List saved audience segments
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product audience/segment access in the effective workspace.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- Returns
- HTTP 200: segments.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/segments
Create a segment
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.
- Request fields
- name: string (required)
- description: string
- filter: object
- Returns
- HTTP 201: segment.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
}
},
"required": [
"name"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/segments/:segmentId
Edit a segment
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.
- Request fields
- name: string
- description: string
- filter: object
- Returns
- HTTP 200: segment.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/segments/:segmentId
Delete a segment
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Returns
- HTTP 200: segment.
- Notes
- marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/marketing/contacts/bulk-suppress
Suppress selected contacts
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- ids: array
- contactIds: array
- reason: string
- filter: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- scope: string
- expectedTotal: integer
- jobId: string
- Returns
- HTTP 200: suppressed, requested, skipped, contacts, jobId, advanced, totalCount, remaining, cumulativeSuppressed, cumulativeSkipped, complete, verificationPending.
- Notes
- Requires marketing.manage and all-products scope. Selected IDs and all-matching cleanup use different checks. All-matching requires a current active-contact filter and expectedTotal; continue using the returned jobId until complete. Changed selection fails rather than silently excluding a new audience. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"contactIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"reason": {
"type": "string"
},
"filter": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"scope": {
"type": "string"
},
"expectedTotal": {
"type": "integer"
},
"jobId": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"suppressed": {
"type": "integer"
},
"requested": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"jobId": {
"type": "string"
},
"advanced": {
"type": "integer"
},
"totalCount": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"cumulativeSuppressed": {
"type": "integer"
},
"cumulativeSkipped": {
"type": "integer"
},
"complete": {
"type": "boolean"
},
"verificationPending": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/marketing/contacts/:id/suppress
Update one contact suppression
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- reason: string
- Returns
- HTTP 200: contact, suppressed.
- Notes
- Requires marketing.manage and all-products scope. Suppression is not deletion of financial records. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
},
"suppressed": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/marketing/growth-flows/:flowId/recipients
Review flow recipients
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query status: string
- query emailNumber: integer
- Returns
- HTTP 200: recipients, pagination, search, status, emailNumber.
- Notes
- For status=queued, inspect sendHoldCode, failureReason and nextRetryAt separately from scheduledFor. A funding hold keeps the planned date and uses a separate retry deadline, normally set 15 minutes after the deferred attempt. Worker selection and claim both respect that deadline. Once funding and spend checks succeed, held work can retry automatically; provider availability, active flow, consent, ownership and queue eligibility still apply. Do not reset the flow or use Retry unconfirmed for an ordinary funding pause. The row may remain queued while sending is paused; a past scheduledFor is not proof of a send.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "emailNumber",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"workflowId": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"status": {
"type": "string"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"scheduledFor": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Planned send date. For a queued funding hold, preserves not_before when recorded, otherwise scheduled_for; not the next funding-retry time."
},
"sendHoldCode": {
"type": [
"string",
"null"
],
"description": "Queued spend/funding hold code, otherwise null. A hold is not provider acceptance or delivery_unknown."
},
"nextRetryAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Queued funding retry eligibility from spendHoldRetryAt, with a legacy scheduled_for fallback. Otherwise null. Not a guaranteed send time."
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendAttemptAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveryReviewedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveryReviewOutcome": {
"type": [
"string",
"null"
]
},
"deliveryReviewComplete": {
"type": "boolean"
},
"deliveryReviewEventsScanned": {
"type": "integer"
},
"retryUnconfirmedAllowed": {
"type": "boolean"
},
"productName": {
"type": "string"
},
"productRole": {
"type": "string"
}
},
"additionalProperties": true
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
}
},
"additionalProperties": true
},
"search": {
"type": "string"
},
"status": {
"type": "string"
},
"emailNumber": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/growth-flows/:flowId/run
Run supported flow work; not a consent override
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- Returns
- HTTP 200: flow, signal, launched.
- Notes
- Launches supported manual audience work. No eligible audience means no permission to send to suppressed contacts.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"flow": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"paused",
"archived"
]
},
"triggerType": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"delayMinutes": {
"type": "integer",
"minimum": 0
},
"quietHoursStrategy": {
"type": "string",
"enum": [
"defer",
"skip",
"ignore"
]
},
"smartTimingEnabled": {
"type": "boolean"
},
"suppressionPolicy": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"messageTemplate": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
}
},
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here.",
"properties": {
"includeFreeAcquisitions": {
"type": "boolean"
}
}
},
"type": {
"type": "string"
},
"description": {
"type": "string"
},
"audienceId": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"includeFreeAcquisitions": {
"type": "boolean",
"description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
},
"relatedProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"promotionId": {
"type": "integer",
"minimum": 1
},
"inactiveDays": {
"type": "integer"
},
"setupUrl": {
"type": "string"
},
"releaseUrl": {
"type": "string"
},
"version": {
"type": "string"
},
"downloadUrl": {
"type": "string"
},
"recommendedProductUrl": {
"type": "string"
},
"incentive": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"type": {
"type": "string"
},
"purchaseRewardOfferId": {
"type": "integer",
"minimum": 1
},
"promoCodeId": {
"type": "integer",
"minimum": 1
},
"promoCode": {
"type": "string"
},
"discountLabel": {
"type": "string"
}
},
"additionalProperties": true
},
"sequence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"delayMinutes": {
"type": "integer"
},
"emailNumber": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
},
"metrics": {
"type": "object",
"properties": {
"queuedNow": {
"type": "integer"
},
"sentTotal": {
"type": "integer"
},
"failedTotal": {
"type": "integer"
},
"unresolvedTotal": {
"type": "integer"
},
"emailsSent": {
"type": "integer"
},
"opens": {
"type": "integer"
},
"clicks": {
"type": "integer"
},
"conversions": {
"type": "integer"
},
"revenue": {
"type": "number"
}
},
"additionalProperties": true
},
"stepMetrics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
},
"signal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"launched": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/campaigns/:campaignId/resume-send
Resume supported interrupted send processing
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- HTTP 200: campaign, processed, sent, failed, deferred, skipped, remainingQueued, pausedUntil.
- Notes
- Resume remaining work, not a new campaign or resend of accepted recipients. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
},
"processed": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"deferred": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"remainingQueued": {
"type": "integer"
},
"pausedUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, CAMPAIGN_NOT_SENDING.
/api/developer/marketing/campaigns/latest/report
Read the latest scoped campaign report
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product campaign/audience access.
- Returns
- HTTP 200: recipients, queued, sending, sent, skipped, failed, unsubscribed, bounced, complained, accepted, completed, remaining, opened, clicked, uniqueOpened, uniqueClicked, delivered, recordedDelivered, deliverySource, lastDeliveryAt, recordedOpenEvents, recordedClickEvents, engagementUnchecked, engagementDenominator, providerBounced, providerUnsubscribed, providerComplaints, performanceSource, providerStatsCheckedAt, providerStatsError, providerStatsStatus, attributedOrders, revenueCents, openRate, clickRate, clickToOpenRate, costCents, costBasis, emailsSentCount, statusBreakdown, progress.
- Notes
- Same availability fields and nullable provider totals as the campaign-specific report. Reports are reads, not provider-history sync or resend commands. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "number"
},
"clickRate": {
"type": "number"
},
"clickToOpenRate": {
"type": "number"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
SoundSync
Promotion workspace
Authenticated developer promotion/product permissions. Review kind, scope, checkout backing, and action eligibility before mutation.
/api/developer/promotions/workspace
List workspace entries and filters
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query kind: string
- query status: string
- query type: string
- query sort: string
- Returns
- HTTP 200: items, summary, pagination, canManage.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "kind",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"pages": {
"type": "integer"
},
"pageSize": {
"type": "integer"
},
"total": {
"type": "integer"
}
},
"additionalProperties": true
},
"canManage": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/workspace/:kind/:id
Read an entry
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: item.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/workspace/:kind/:id/performance
Read activity/performance
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: purchases, revenue, rewards.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"purchases": {
"type": "integer"
},
"revenue": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"amountCents": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"rewards": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/workspace/:kind
Create a supported kind
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 201: item.
- Notes
- kind is code or offer. offerType:tiered_cart_discount accepts productIds, activation:automatic|code and quantityTiers:[{quantity,discountPercent}]. Thresholds count distinct eligible positive-priced one-time products, not units; the highest reached threshold applies to every eligible copy. Use POST /offers for the same per-type eligibility details. New reward coupons use the fixed $9.99 minimum spend.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/workspace/:kind/:id
Update the entry
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: item.
- Notes
- Supported discount type/value changes are saved without changing the code identity or historical receipt snapshots. Code identity, product scope and other immutable offer-family fields still follow their existing rules; duplicate the promotion for a different immutable configuration. Archived records must be restored before editing; deleted records are unavailable.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/workspace/:kind/:id/:action
Run a supported archive/restore or reconciliation action
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: item, checked, released, pending, needsReview, processed, completed, failed, skipped.
- Notes
- action is archive, restore, reconcile-reservations or retry-rewards. Archive/restore return the item; reservation recovery returns checked/released/pending/needsReview; reward recovery returns processed/completed/failed/skipped. Reward retry only applies to purchase-reward offers; these recovery operations are not dry runs.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checked": {
"type": "integer"
},
"released": {
"type": "integer"
},
"pending": {
"type": "integer"
},
"needsReview": {
"type": "integer"
},
"processed": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"skipped": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/promo-codes/import/preview
Validate an import before applying it
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- csv: string
- csvText: string
- defaults: object
- customerMode: ignore | email_specific
- useDefaultForZeroDiscount: boolean
- sourceFilename: string
- diagnostics: boolean
- Returns
- HTTP 200: import, summary, rows, preview, warnings, errors.
- Notes
- CSV is a JSON string, not a multipart upload. Inspect every warning and duplicate before import.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"csv": {
"type": "string"
},
"csvText": {
"type": "string"
},
"defaults": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"customerMode": {
"type": "string",
"enum": [
"ignore",
"email_specific"
]
},
"useDefaultForZeroDiscount": {
"type": "boolean"
},
"sourceFilename": {
"type": "string"
},
"diagnostics": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"import": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"summary": {
"type": "object",
"properties": {
"imported": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"invalid": {
"type": "integer"
}
},
"additionalProperties": true
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"preview": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/promo-codes/import
Apply a permitted coupon import
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- csv: string
- csvText: string
- defaults: object
- customerMode: ignore | email_specific
- useDefaultForZeroDiscount: boolean
- sourceFilename: string
- diagnostics: boolean
- Returns
- HTTP 201: import, summary, rows, preview, warnings, errors.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"csv": {
"type": "string"
},
"csvText": {
"type": "string"
},
"defaults": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"customerMode": {
"type": "string",
"enum": [
"ignore",
"email_specific"
]
},
"useDefaultForZeroDiscount": {
"type": "boolean"
},
"sourceFilename": {
"type": "string"
},
"diagnostics": {
"type": "boolean"
}
},
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"import": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"summary": {
"type": "object",
"properties": {
"imported": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"invalid": {
"type": "integer"
}
},
"additionalProperties": true
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"preview": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/promotions/promo-codes/imports/:importJobId
Inspect import results
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: import, summary, rows, preview, warnings, errors.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"import": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"summary": {
"type": "object",
"properties": {
"imported": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"invalid": {
"type": "integer"
}
},
"additionalProperties": true
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"preview": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
SoundSync
Custom-domain analytics
Developer settings require the authenticated workspace, all-product scope, and settings permissions. Public storefront config is host-resolved and is not a developer report.
/api/developer/google-analytics
Read settings and management capability
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.
- Notes
- Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"measurementId": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"domain": {
"type": "string"
},
"domainStatus": {
"type": "string"
},
"trackingReady": {
"type": "boolean"
},
"canManage": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/google-analytics
Save supported GA4 settings
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- measurementId: string (required)
- Returns
- HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.
- Notes
- Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"measurementId": {
"type": "string",
"pattern": "^G-[A-Z0-9]+$"
}
},
"required": [
"measurementId"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"measurementId": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"domain": {
"type": "string"
},
"domainStatus": {
"type": "string"
},
"trackingReady": {
"type": "boolean"
},
"canManage": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/google-analytics
Disconnect GA4 settings
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.
- Notes
- Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"measurementId": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"domain": {
"type": "string"
},
"domainStatus": {
"type": "string"
},
"trackingReady": {
"type": "boolean"
},
"canManage": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/storefronts/analytics
Resolve public tracking config for the requested host
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query host: string (required)
- Returns
- HTTP 200: enabled, measurementId, domain.
Request, response and error reference
Query and header parameters
[
{
"name": "host",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
]
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"measurementId": {
"type": [
"string",
"null"
]
},
"domain": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
SoundSync
Customer operations
Authenticated developer/customer access is checked for the relevant record. A visibility change, access removal, and refund are different actions.
/api/developer/customers/:customerId
Edit supported customer fields
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- firstName: string,null
- lastName: string,null
- email: string
- phone: string,null
- newPassword: string. Optional replacement store password, at most 72 UTF-8 bytes. Never log it.
- reason: string
- confirm: boolean
- confirmation: string
- Returns
- HTTP 200: ok, message, scope, passwordChanged, password_changed, customer.
- Notes
- Requires customers.manage and all-products scope, plus confirm:true or confirmation:"yes". Names, email, phone and an optional store password affect only this developer relationship. Marketing contacts, supported queued messages and current contact references follow that store edit, with later activity/imports retaining its corrected details. Shared SoundSync login credentials, verification, recovery, Stripe billing identity and other stores are not edited. Store email/password changes invalidate old store credential sessions and reset links only. Names can be cleared independently; first_name/last_name and generatedPassword/generated_password compatibility aliases remain accepted. Unlinked contacts cannot receive a login password until an account is linked. Issued invoices, access ownership and sent messages are not rewritten; saved suppressions remain protected.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": [
"string",
"null"
]
},
"newPassword": {
"type": "string",
"minLength": 8,
"description": "Optional replacement store password, at most 72 UTF-8 bytes. Never log it."
},
"reason": {
"type": "string"
},
"confirm": {
"type": "boolean"
},
"confirmation": {
"type": "string"
}
},
"additionalProperties": true,
"anyOf": [
{
"properties": {
"confirm": {
"const": true
}
},
"required": [
"confirm"
]
},
{
"properties": {
"confirmation": {
"type": "string",
"pattern": "^\\s*[Yy][Ee][Ss]\\s*$"
}
},
"required": [
"confirmation"
]
}
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"message": {
"type": "string"
},
"scope": {
"const": "storefront"
},
"passwordChanged": {
"type": "boolean"
},
"password_changed": {
"type": "boolean"
},
"customer": {
"type": "object",
"properties": {
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: CUSTOMER_CONTACT_CONFLICT, INVALID_CUSTOMER_PASSWORD.
/api/developer/customers/:customerId/resend-verification
Resend the supported verification message
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: success, sent, sentTo, providerMessageId, message, customer.
- Notes
- Requires customers.manage, all-products scope and a linked account. Already-verified accounts return without another send; delivery failures can return 424.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"sent": {
"type": "boolean"
},
"sentTo": {
"type": "string",
"format": "email"
},
"providerMessageId": {
"type": [
"string",
"null"
]
},
"message": {
"type": "string"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"email_verification_status": {
"type": "string"
},
"account_email": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 424, 429, 500, 503.
/api/developer/serials/:serialId/activations
Inspect device activations
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: serial, activations, current_activations, max_activations, remaining_activations.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"serial": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"activations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"instance_id": {
"type": "string"
},
"active": {
"type": "boolean"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"current_activations": {
"type": "integer"
},
"max_activations": {
"type": "integer"
},
"remaining_activations": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/serials/:serialId/activations/:activationId/deactivate
Deactivate the selected device
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- reason: string
- note: string
- Returns
- HTTP 200: activation, current_activations, max_activations, remaining_activations.
- Notes
- Scoped administrative device release, not a refund or entitlement deletion. A changed activation can return 409.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"note": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"activation": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"active": {
"const": false
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"current_activations": {
"type": "integer"
},
"max_activations": {
"type": "integer"
},
"remaining_activations": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/purchases/:orderId/invoice.pdf
Read an authorized invoice
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: application/pdf.
- Notes
- Returns a private invoice attachment. INVOICE_PAGINATION_REQUIRED is an error rather than a truncated invoice.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/pdf)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 500, 503.
/api/developer/purchases/:orderItemId/remove-access
Remove selected access under the supported policy
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- reason: string
- note: string
- deleteRecord: boolean
- mode: string
- action: string
- entitlementId: integer
- Returns
- HTTP 200: success, removedFromCustomerAccount, removedFromDeveloperPurchases, orderId, orderItemId, customerId, productId, product, recordOnly, revokedEntitlements, revokedSerials, deactivatedActivations, message.
- Notes
- Removes the selected purchase access and optionally hides its record. This does not issue a provider refund. For a manual history row with metadata.manualGrantExistingAccess:true, removal without deleteRecord:true returns 409 MANUAL_GRANT_HISTORY_ONLY. deleteRecord:true hides that history only and returns recordOnly:true with zero revocations; manage the original entitlement or serial separately. Access-only ACCESS references are not order-item IDs. Partner/pool/manual subscription purchase identifiers have their own supported handling; inspect the returned result.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"note": {
"type": "string"
},
"deleteRecord": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"action": {
"type": "string"
},
"entitlementId": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"removedFromCustomerAccount": {
"type": "boolean"
},
"removedFromDeveloperPurchases": {
"type": "boolean"
},
"orderId": {
"type": "integer",
"minimum": 1
},
"orderItemId": {
"type": "integer",
"minimum": 1
},
"customerId": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"product": {
"type": "string"
},
"recordOnly": {
"type": "boolean"
},
"revokedEntitlements": {
"type": "integer"
},
"revokedSerials": {
"type": "integer"
},
"deactivatedActivations": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: MANUAL_GRANT_HISTORY_ONLY.
/api/library/redeem-serial
Customer serial claim; ownership proof still applies
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- serial: string
- serialCode: string
- serial_code: string
- code: string
- Returns
- HTTP 200: message, product, serial, entitlement, created.
- Notes
- Send one supported serial alias. Account ownership, redeemed/revoked state and current product access are checked. Repeated owned access can return created:false.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"serial": {
"type": "string"
},
"serialCode": {
"type": "string"
},
"serial_code": {
"type": "string"
},
"code": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"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
},
"serial": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"code": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
},
"entitlement": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"state": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
},
"created": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/library/orders/:orderId/invoice.pdf
Customer-authorized order invoice
- 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.
- Returns
- HTTP 200: application/pdf.
- Notes
- Requires customer account identity, not a shared download token. Only owned orders are returned; invoice generation unavailability is an error. 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
No request body fields are read by this operation.
HTTP 200 response (application/pdf)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 500, 503, 401, 403.
Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED, CUSTOMER_ACCOUNT_RESTRICTED, CUSTOMER_STORE_CLOSED, CUSTOMER_ACCOUNT_REQUIRED.
SoundSync
Rent-to-own test integration
Developer settings require workspace permissions; customer agreement operations require customer authentication. Production live checkout is explicitly unavailable.
/api/developer/rent-to-own/settings
Read developer defaults
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: settings.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"defaultBillingInterval": {
"type": "string"
},
"defaultInstallmentCount": {
"type": "integer"
},
"minInstallmentCount": {
"type": "integer"
},
"maxInstallmentCount": {
"type": "integer"
},
"defaultPriceStrategy": {
"type": "string"
},
"defaultPremiumBps": {
"type": "integer"
},
"minCashPriceCents": {
"type": "integer",
"minimum": 0
},
"maxCashPriceCents": {
"type": "integer",
"minimum": 0
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"allowEarlyPayoff": {
"type": "boolean"
},
"customerTermsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/rent-to-own/settings
Update defaults
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- enabled: boolean
- defaultBillingInterval: string
- defaultInstallmentCount: integer
- minInstallmentCount: integer
- maxInstallmentCount: integer
- defaultPriceStrategy: string
- defaultPremiumBps: integer
- minCashPriceCents: integer
- maxCashPriceCents: integer
- failedPaymentGraceDays: integer
- cancellationBehavior: string
- promotionPolicy: string
- allowEarlyPayoff: boolean
- customerTermsUrl: string
- displayTitle: string
- displayDisclaimer: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: settings.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"defaultBillingInterval": {
"type": "string"
},
"defaultInstallmentCount": {
"type": "integer"
},
"minInstallmentCount": {
"type": "integer"
},
"maxInstallmentCount": {
"type": "integer"
},
"defaultPriceStrategy": {
"type": "string"
},
"defaultPremiumBps": {
"type": "integer"
},
"minCashPriceCents": {
"type": "integer",
"minimum": 0
},
"maxCashPriceCents": {
"type": "integer",
"minimum": 0
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"allowEarlyPayoff": {
"type": "boolean"
},
"customerTermsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"defaultBillingInterval": {
"type": "string"
},
"defaultInstallmentCount": {
"type": "integer"
},
"minInstallmentCount": {
"type": "integer"
},
"maxInstallmentCount": {
"type": "integer"
},
"defaultPriceStrategy": {
"type": "string"
},
"defaultPremiumBps": {
"type": "integer"
},
"minCashPriceCents": {
"type": "integer",
"minimum": 0
},
"maxCashPriceCents": {
"type": "integer",
"minimum": 0
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"allowEarlyPayoff": {
"type": "boolean"
},
"customerTermsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/rent-to-own
Read product override
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: settings.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"billingInterval": {
"type": "string"
},
"installmentCount": {
"type": "integer"
},
"priceStrategy": {
"type": "string"
},
"premiumBps": {
"type": "integer"
},
"fixedTotalCents": {
"type": "integer",
"minimum": 0
},
"fixedInstallmentCents": {
"type": "integer",
"minimum": 0
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/rent-to-own
Update product override
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- enabled: boolean
- billingInterval: string
- installmentCount: integer
- priceStrategy: string
- premiumBps: integer
- fixedTotalCents: integer
- fixedInstallmentCents: integer
- promotionPolicy: string
- failedPaymentGraceDays: integer
- cancellationBehavior: string
- displayTitle: string
- displayDisclaimer: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: settings.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"billingInterval": {
"type": "string"
},
"installmentCount": {
"type": "integer"
},
"priceStrategy": {
"type": "string"
},
"premiumBps": {
"type": "integer"
},
"fixedTotalCents": {
"type": "integer",
"minimum": 0
},
"fixedInstallmentCents": {
"type": "integer",
"minimum": 0
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"billingInterval": {
"type": "string"
},
"installmentCount": {
"type": "integer"
},
"priceStrategy": {
"type": "string"
},
"premiumBps": {
"type": "integer"
},
"fixedTotalCents": {
"type": "integer",
"minimum": 0
},
"fixedInstallmentCents": {
"type": "integer",
"minimum": 0
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/products/:productId/rent-to-own/preview
Preview the configured option
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: option, productSettings, effectiveSettings.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"option": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"eligible": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"ineligibilityReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"currency": {
"type": "string"
},
"cashPriceCents": {
"type": "integer",
"minimum": 0
},
"installmentAmountCents": {
"type": "integer",
"minimum": 0
},
"installmentCount": {
"type": "integer"
},
"totalContractCents": {
"type": "integer",
"minimum": 0
},
"roundingAdjustmentCents": {
"type": "integer"
},
"billingInterval": {
"type": "string"
},
"priceStrategy": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"termsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"productionExposureAllowed": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productSettings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"billingInterval": {
"type": "string"
},
"installmentCount": {
"type": "integer"
},
"priceStrategy": {
"type": "string"
},
"premiumBps": {
"type": "integer"
},
"fixedTotalCents": {
"type": "integer",
"minimum": 0
},
"fixedInstallmentCents": {
"type": "integer",
"minimum": 0
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"effectiveSettings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"defaultBillingInterval": {
"type": "string"
},
"defaultInstallmentCount": {
"type": "integer"
},
"minInstallmentCount": {
"type": "integer"
},
"maxInstallmentCount": {
"type": "integer"
},
"defaultPriceStrategy": {
"type": "string"
},
"defaultPremiumBps": {
"type": "integer"
},
"minCashPriceCents": {
"type": "integer",
"minimum": 0
},
"maxCashPriceCents": {
"type": "integer",
"minimum": 0
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"allowEarlyPayoff": {
"type": "boolean"
},
"customerTermsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/rent-to-own/products/:productId/option
Public product option
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: option.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"option": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"eligible": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"ineligibilityReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"currency": {
"type": "string"
},
"cashPriceCents": {
"type": "integer",
"minimum": 0
},
"installmentAmountCents": {
"type": "integer",
"minimum": 0
},
"installmentCount": {
"type": "integer"
},
"totalContractCents": {
"type": "integer",
"minimum": 0
},
"roundingAdjustmentCents": {
"type": "integer"
},
"billingInterval": {
"type": "string"
},
"priceStrategy": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"termsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"productionExposureAllowed": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/rent-to-own/checkout
Authenticated test checkout; production live requests rejected
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- productId: integer (required)
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- successUrl: string
- cancelUrl: string
- Returns
- HTTP 201: rentToOwnCheckout, productionExposureAllowed, url, checkoutUrl, checkoutSession, checkoutSessionRecord, planVersion, option.
- Notes
- Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"successUrl": {
"type": "string"
},
"cancelUrl": {
"type": "string"
}
},
"required": [
"productId"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"rentToOwnCheckout": {
"type": "boolean"
},
"productionExposureAllowed": {
"const": false
},
"url": {
"type": [
"string",
"null"
]
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"checkoutSession": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"checkoutSessionRecord": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"planVersion": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"option": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"eligible": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"ineligibilityReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"currency": {
"type": "string"
},
"cashPriceCents": {
"type": "integer",
"minimum": 0
},
"installmentAmountCents": {
"type": "integer",
"minimum": 0
},
"installmentCount": {
"type": "integer"
},
"totalContractCents": {
"type": "integer",
"minimum": 0
},
"roundingAdjustmentCents": {
"type": "integer"
},
"billingInterval": {
"type": "string"
},
"priceStrategy": {
"type": "string"
},
"promotionPolicy": {
"type": "string"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"cancellationBehavior": {
"type": "string"
},
"termsUrl": {
"type": "string"
},
"displayTitle": {
"type": "string"
},
"displayDisclaimer": {
"type": "string"
},
"productionExposureAllowed": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 409, 500, 503.
/api/rent-to-own/customer/agreements
List the customer's agreements
- Auth
- Account Bearer session token
- Scope
- Same buyer-ownership checks as customer agreement detail.
- Request fields
- query developerId: integer
- query status: string
- query limit: integer
- Returns
- HTTP 200: agreements.
Request, response and error reference
Query and header parameters
[
{
"name": "developerId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"agreements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"customerUserId": {
"type": [
"integer",
"null"
]
},
"customerId": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": [
"string",
"null"
]
},
"planVersionId": {
"type": "integer",
"minimum": 1
},
"checkoutId": {
"type": [
"integer",
"null"
]
},
"entitlementId": {
"type": [
"integer",
"null"
]
},
"provider": {
"type": "string"
},
"providerSubscriptionId": {
"type": [
"string",
"null"
]
},
"environment": {
"type": "string"
},
"status": {
"type": "string"
},
"accessState": {
"type": "string"
},
"ownershipState": {
"type": "string"
},
"currency": {
"type": "string"
},
"cashPriceCents": {
"type": "integer"
},
"installmentAmountCents": {
"type": "integer"
},
"installmentCount": {
"type": "integer"
},
"totalContractCents": {
"type": "integer"
},
"paidInstallmentCount": {
"type": "integer"
},
"netPaidInstallmentCount": {
"type": "integer"
},
"paidAmountCents": {
"type": "integer"
},
"refundedAmountCents": {
"type": "integer"
},
"disputedAmountCents": {
"type": "integer"
},
"currentPeriodStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currentPeriodEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"nextPaymentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failedPaymentGraceUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelAtPeriodEnd": {
"type": "boolean"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"ownedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"revokedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"installments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"installmentNumber": {
"type": "integer"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amountDueCents": {
"type": "integer"
},
"amountPaidCents": {
"type": "integer"
},
"amountRefundedCents": {
"type": "integer"
},
"taxAmountCents": {
"type": "integer"
},
"discountAmountCents": {
"type": "integer"
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"disputedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"orderId": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
}
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/rent-to-own/customer/agreements/:agreementId/cancel
Cancel a permitted customer agreement
- Auth
- Account Bearer session token
- Scope
- Signed-in buyer only; authenticated identity and route agreement ID cannot be supplied in the body.
- Request fields
- reason: string
- Returns
- HTTP 200: agreement, immediate, unchanged.
- Notes
- Only reason is customer-editable. The saved agreement cancellationBehavior is authoritative, defaulting to access_until_period_end for legacy agreements. Body policy overrides are ignored. Repeated requests preserve local cancellation with unchanged:true. A pending provider step is retried with the same provider idempotency key; a recorded confirmed step is not sent again. Provider failure returns 502 rent_to_own_cancellation_pending with retryable:true and localCancellationSaved:true. Read metadata.providerCancellation.status; pending is not provider confirmation. Retry this same cancellation request, not a checkout or charge. There is no automatic retry timing promise. Completed/owned, refunded, disputed, revoked or ownership-revoked agreements return 409. Period-end cancellation preserves pending, past-due, grace and suspended lifecycle states, so existing expiry checks still run; it does not upgrade them to paid access. Live rent-to-own checkout remains unavailable; this does not enable new production installment sales.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"agreement": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"customerUserId": {
"type": [
"integer",
"null"
]
},
"customerId": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": [
"string",
"null"
]
},
"planVersionId": {
"type": "integer",
"minimum": 1
},
"checkoutId": {
"type": [
"integer",
"null"
]
},
"entitlementId": {
"type": [
"integer",
"null"
]
},
"provider": {
"type": "string"
},
"providerSubscriptionId": {
"type": [
"string",
"null"
]
},
"environment": {
"type": "string"
},
"status": {
"type": "string"
},
"accessState": {
"type": "string"
},
"ownershipState": {
"type": "string"
},
"currency": {
"type": "string"
},
"cashPriceCents": {
"type": "integer"
},
"installmentAmountCents": {
"type": "integer"
},
"installmentCount": {
"type": "integer"
},
"totalContractCents": {
"type": "integer"
},
"paidInstallmentCount": {
"type": "integer"
},
"netPaidInstallmentCount": {
"type": "integer"
},
"paidAmountCents": {
"type": "integer"
},
"refundedAmountCents": {
"type": "integer"
},
"disputedAmountCents": {
"type": "integer"
},
"currentPeriodStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currentPeriodEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"nextPaymentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failedPaymentGraceUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelAtPeriodEnd": {
"type": "boolean"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"ownedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"revokedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"installments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"installmentNumber": {
"type": "integer"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amountDueCents": {
"type": "integer"
},
"amountPaidCents": {
"type": "integer"
},
"amountRefundedCents": {
"type": "integer"
},
"taxAmountCents": {
"type": "integer"
},
"discountAmountCents": {
"type": "integer"
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"disputedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"orderId": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
}
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"immediate": {
"type": "boolean"
},
"unchanged": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 502, 503.
Operation errors: rent_to_own_cancellation_pending.
SoundSync
Detailed contracts and workflows
Licensing
Product authentication and access decisions.
Partner
External-order fields, scopes, idempotency, and errors.
WooCommerce
Mapping and fulfillment decisions.
Marketing
Campaign and audience contracts.
Promotions
Supported offer fields.
Delivery
Upload stages and customer authorization.
Google Analytics
Host and privacy boundaries.
SoundSync
Refunds, recipient programs, and automation
Developer refunds
Original-payment preview, whole-product selection, confirmation, and operation states.
Affiliate and collaborator programs
Agreements, live consent, attribution, balances, and destination setup.
Growth flows
Sequences, test sends, suppression, queue, and trigger activity.
Keep-your-products bundles
Paid invoice ownership and refund/dispute effects.
SoundSync
Catalog, upload, and branding contracts
Package download response
Package generation/download preparation returns JSON with url, filename, and expiresIn. Retrieve the ZIP through the returned signed URL within 300 seconds. Busy (429) and unavailable-configuration (503) responses are not downloadable archives.
SoundSync
Package and ownership references
SoundSync
Private catalog, artwork drafts and billing exports
/api/developer/products/catalog
Search the private developer catalog
- Auth
- Account Bearer session token
- Scope
- products.view and permitted products.
- Request fields
- query search: string
- query q: string
- query status: value
- query type: string
- query category: string
- query licensing: string
- query sort: value
- query view: value
- query page: integer
- query limit: integer
- query currency: string
- query environment: string
- Returns
- HTTP 200: summary, products, pagination, filters.
- Notes
- Requires products.view and returns only permitted products. This is a private dashboard catalog, not the public marketplace. Default status all excludes archived products; request archived explicitly. Page is clamped to available pages. The summary covers permitted catalog products, not only the filtered page. monthlySalesAvailable:false and null totals mean reporting is unavailable, not zero sales. hisePackageEligible is a compatibility field for activation capability, not a statement that a product uses HISE.
Request, response and error reference
Query and header parameters
[
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"enum": [
"all",
"published",
"draft",
"hidden",
"archived",
"needs_review"
]
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "licensing",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"enum": [
"updated",
"name_az",
"name_za",
"newest",
"oldest",
"sales",
"downloads"
]
},
"required": false,
"description": ""
},
{
"name": "view",
"in": "query",
"schema": {
"enum": [
"table",
"grid"
]
},
"required": false,
"description": ""
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 5,
"maximum": 50,
"default": 10
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"summary": {
"type": "object",
"properties": {
"totalProducts": {
"type": "integer"
},
"archived": {
"type": "integer"
},
"published": {
"type": "integer"
},
"drafts": {
"type": "integer"
},
"hidden": {
"type": "integer"
},
"needsAttention": {
"type": "integer"
},
"monthlySalesAvailable": {
"type": "boolean"
},
"monthlySalesCents": {
"type": [
"number",
"null"
]
},
"monthlySales": {
"type": [
"number",
"null"
]
},
"monthlySalesDeltaPercent": {
"type": [
"number",
"null"
]
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
}
},
"additionalProperties": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"sku": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"typeLabel": {
"type": "string"
},
"category": {
"type": "string"
},
"thumbnailUrl": {
"type": "string"
},
"status": {
"type": "string"
},
"storefrontStatus": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"salePrice": {
"type": [
"number",
"null"
]
},
"currency": {
"type": "string"
},
"licensingType": {
"type": "string"
},
"downloads": {
"type": [
"number",
"null"
]
},
"sales": {
"type": "number"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"needsAttention": {
"type": "boolean"
},
"attentionReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"hisePackageEligible": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
}
},
"additionalProperties": true
},
"filters": {
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"types": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": true
}
},
"statuses": {
"type": "array",
"items": {
"type": "string"
}
},
"licensingTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
/api/developer/products/:productId/marketplace-assets/render-preview
Render a private image without saving
- Auth
- Account Bearer session token
- Scope
- products.view and assigned-product access.
- Request fields
- placementType: string
- presentationMode: string
- templateId: string
- sourceAssetId: integer
- palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: review the response schema below.
- Notes
- Requires products.view and assigned-product access. Renders a private draft image in memory; there is no render job, upload, saved profile change, activation or publication. Send one placementType (default standard_product_cover), not placements. sourceAssetId selects an owned usable source; settings and palette customize this draft. Snake-case placement_type/presentation_mode/source_asset_id/template_id aliases are accepted. Returns binary image/png or image/webp according to the placement, not JSON/base64. Cache-Control is private, no-store. Missing sources or unsupported placements are errors, not a reason to publish a fallback.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"placementType": {
"type": "string"
},
"presentationMode": {
"type": "string"
},
"templateId": {
"type": "string"
},
"sourceAssetId": {
"type": "integer",
"minimum": 1
},
"palette": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
HTTP 200 response (image/png)
{
"type": "string",
"format": "binary"
}HTTP 200 response (image/webp)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 401, 403, 404, 500, 503.
/api/developer/billing/invoices/:invoiceId/download.csv
Download the developer billing invoice CSV
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products scope.
- Returns
- HTTP 200: text/csv.
- Notes
- Requires billing.view and all-products scope. Downloads the owned developer-billing invoice as CSV, not a customer purchase invoice or payment receipt. Read Content-Disposition for the filename. Returns 404 BILLING_INVOICE_NOT_FOUND for an unavailable invoice.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 500, 503.
/api/developer/billing/statements/:statementId/download.csv
Download the developer billing statement CSV
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products scope.
- Returns
- HTTP 200: text/csv.
- Notes
- Requires billing.view and all-products scope. Downloads the owned monthly billing statement as CSV, not a payout execution or confirmation of bank receipt. Read Content-Disposition for the filename. Returns 404 BILLING_STATEMENT_NOT_FOUND for an unavailable statement.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}
Documented failures: 400, 500, 503.
SoundSync
Manage the full product workflow
Product Management API
Drafts, publication, files and reviewed AI suggestions.
Developer Onboarding API
Resumable account setup, business, selling experience and readiness.
Reseller Partner Portal API
Membership, relationship records, conversations and approved store connections.
Partner Hub Management API
Relationships, product assignments, serial inventory, conversations and retired write boundaries.
Customer and Serial Management API
Current inventory, imports, access actions and purchase tables.
Domain Setup API
Provider instructions, DNS checks, progress and sender identity.
API Surfaces and Coverage
Public integrations versus first-party and internal operations.
Expansion API
Parent requirements and owned-product relationships.
Support Content API
Contact routing, articles and assistance settings.
Rent-to-Own Agreement API
Installment history, buyer ownership and cancellation.
Licensing Rules and Delivery API
Rules, file versions, activity and connection diagnostics.
Operational AI Draft API
Suggestions, persistence and review status.
Storefront Management API
Website configuration, catalog placements and AI drafts.
Brand Assets API
Public uploads, link checks and sender tests.
Embedded Content API
Published pages, bundles and customer pricing previews.
SoundSync
Review, reporting and product access
SoundSync
