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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/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.
GET
/api/developer/products/:productId/marketplace-assets
Asset builder overview
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/marketplace-assets/preview
Private placement preview
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/marketplace-assets/preview/:placementType
One private placement preview
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/organize
Organize source assets
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/source-assets
Upload guarded source images
- Auth
- Account Bearer JWT
- 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.
PATCH
/api/developer/products/:productId/marketplace-assets/source-assets/:assetId
Update source metadata
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/source-assets/:assetId/extraction
Request product-interface extraction
- Auth
- Account Bearer JWT
- 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.
PATCH
/api/developer/products/:productId/marketplace-assets/masks/:maskId
Save mask correction
- Auth
- Account Bearer JWT
- 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.
PATCH
/api/developer/products/:productId/marketplace-assets/profile
Update placement profile
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/marketplace-assets/templates
List supported templates
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/render-jobs
Queue a render or placement family
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/ensure-core-set
Prepare the supported core placements
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/marketplace-assets/render-jobs/:jobId
Inspect render progress/result
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId/approval
Change approval deliberately
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId/restore
Restore a generated asset
- Auth
- Account Bearer JWT
- 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.
DELETE
/api/developer/products/:productId/marketplace-assets/generated-assets/:assetId
Delete the selected generated asset
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/replacements/:placementType
Upload one custom replacement
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/ensure/:placementType
Prepare a particular placement
- Auth
- Account Bearer JWT
- 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.
POST
/api/subscriptions/bundles/cancel-scheduled-change
Cancel an eligible pending plan change
- Auth
- Account Bearer JWT
- 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.
POST
/api/subscriptions/bundles/billing-portal
Open the permitted provider billing portal
- Auth
- Account Bearer JWT
- 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.
POST
/api/subscriptions/bundles/manual-billing-setup
Start customer-authorized billing setup for a manual grant
- Auth
- Account Bearer JWT
- 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.
POST
/api/subscriptions/bundles/manual-billing-preview
Preview the proposed billing conversion
- Auth
- Account Bearer JWT
- 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.
POST
/api/subscriptions/bundles/manual-billing-confirm
Confirm the supported billing setup
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/juce-package
Prepare the product source package and return a private download link
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/juce-package/download
Download the product package
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/juce-package/generate
Generate the product-specific package
- Auth
- Account Bearer JWT
- 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.
POST
/api/products/:id/files/direct-uploads
Start a direct upload; return job and signed PUT instructions
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/direct-uploads/:jobId/complete
Verify stored size and session, then attach the file
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/uploads/chunk-sessions
Start a local chunk session
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/uploads/chunk-sessions/:uploadId/chunks
Upload a multipart chunk
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/uploads/chunk-sessions/:uploadId/complete
Complete chunk assembly
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/upload-link
Prepare a permitted remote upload
- Auth
- Account Bearer JWT
- 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.
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.
GET
/api/products/:id/files/uploads/:jobId
Read job state
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
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.
POST
/api/products/:id/files/uploads/:jobId/retry
Retry supported failed work
- Auth
- Account Bearer JWT
- 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.
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.
POST
/api/products/:id/files/uploads/:jobId/cancel
Cancel the upload job
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: job, upload, processing, deduplicated, file, product.
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.
GET
/api/products/:id/files/:fileId/download
Authorized developer file download
- Auth
- Account Bearer JWT
- 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.
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.
GET
/api/developer/partners/resellers/:relationshipId/woocommerce-stores
List related store connections
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
GET
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId
Inspect connection and catalog review
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
PUT
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/mappings
Approve/update a product mapping
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
DELETE
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/mappings
Remove a mapping
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
POST
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/catalog/:catalogItemId/suggestion
Review the suggested mapping
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
POST
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/confirm-exact-mappings
Confirm the supported exact-match review
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
POST
/api/developer/partners/resellers/:relationshipId/woocommerce-stores/:connectionId/activate
Activate the reviewed connection
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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.
GET
/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
}
GET
/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
}
POST
/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, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, customer, items.
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"
},
"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"
},
"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"
},
"fulfillment_status": {
"type": "string"
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 403, 404, 409.
GET
/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, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, 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"
},
"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"
},
"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"
},
"fulfillment_status": {
"type": "string"
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
POST
/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.
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, 403, 404, 409.
POST
/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.
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, 403, 404, 409.
GET
/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. External seller payments remain outside SoundSync managed-checkout processing coverage.
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.
GET
/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. External seller payments remain outside SoundSync managed-checkout processing coverage.
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.
GET
/api/developer/marketing/segments
List saved audience segments
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- 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
}
},
"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
}
},
"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
}
},
"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.
POST
/api/developer/marketing/segments
Create a segment
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- 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
}
},
"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
}
},
"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
}
},
"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
}
},
"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.
PATCH
/api/developer/marketing/segments/:segmentId
Edit a segment
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- 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
}
},
"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
}
},
"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
}
},
"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
}
},
"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.
DELETE
/api/developer/marketing/segments/:segmentId
Delete a segment
- Auth
- Account Bearer JWT
- 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
}
},
"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
}
},
"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
}
},
"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.
PATCH
/api/developer/marketing/contacts/bulk-suppress
Suppress selected contacts
- Auth
- Account Bearer JWT
- 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.
PATCH
/api/developer/marketing/contacts/:id/suppress
Update one contact suppression
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/marketing/growth-flows/:flowId/recipients
Review flow recipients
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- 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
- Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery.
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"
},
"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.
POST
/api/developer/marketing/growth-flows/:flowId/run
Run supported flow work; not a consent override
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- 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."
},
"type": {
"type": "string"
},
"description": {
"type": "string"
},
"audienceId": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"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"
},
"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.
POST
/api/developer/marketing/campaigns/:campaignId/resume-send
Resume supported interrupted send processing
- Auth
- Account Bearer JWT
- 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. 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.
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
}
},
"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"
},
"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
}
},
"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, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_SENDING.
GET
/api/developer/marketing/campaigns/latest/report
Read the latest scoped campaign report
- Auth
- Account Bearer JWT
- 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, 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.
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"
},
"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.
GET
/api/developer/promotions/workspace
List workspace entries and filters
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/promotions/workspace/:kind/:id
Read an entry
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/promotions/workspace/:kind/:id/performance
Read activity/performance
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/promotions/workspace/:kind
Create a supported kind
- Auth
- Account Bearer JWT
- 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.
PATCH
/api/developer/promotions/workspace/:kind/:id
Update the entry
- Auth
- Account Bearer JWT
- 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
- Code, products and discount can be immutable after creation; duplicate the promotion for a different immutable configuration. Archived records must be restored before editing.
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.
POST
/api/developer/promotions/workspace/:kind/:id/:action
Run a supported archive/restore or reconciliation action
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/promotions/promo-codes/import/preview
Validate an import before applying it
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/promotions/promo-codes/import
Apply a permitted coupon import
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/promotions/promo-codes/imports/:importJobId
Inspect import results
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/google-analytics
Read settings and management capability
- Auth
- Account Bearer JWT
- 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.
PUT
/api/developer/google-analytics
Save supported GA4 settings
- Auth
- Account Bearer JWT
- 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.
DELETE
/api/developer/google-analytics
Disconnect GA4 settings
- Auth
- Account Bearer JWT
- 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.
GET
/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.
PATCH
/api/developer/customers/:customerId
Edit supported customer fields
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- firstName: string,null
- lastName: string,null
- email: string
- phone: string,null
- reason: string
- confirm: boolean
- confirmation: string
- Returns
- HTTP 200: ok, message, passwordChanged, password_changed, customer.
- Notes
- Requires customers.manage and all-products scope, plus confirm:true or confirmation:"yes". Names can be cleared independently; first_name/last_name aliases remain accepted. A linked login email cannot be changed here; the customer uses verified account settings. Password replacement is rejected, including legacy generatedPassword/generated_password input. An exclusive unlinked contact email correction clears verification. Supported name/phone corrections can affect the shared profile. Issued invoices and sent messages are not rewritten.
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"
]
},
"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"
},
"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_EMAIL_VERIFICATION_REQUIRED, CUSTOMER_ACCOUNT_RECOVERY_REQUIRED, CUSTOMER_IDENTITY_REVIEW_REQUIRED.
POST
/api/developer/customers/:customerId/resend-verification
Resend the supported verification message
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/serials/:serialId/activations
Inspect device activations
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/serials/:serialId/activations/:activationId/deactivate
Deactivate the selected device
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/purchases/:orderId/invoice.pdf
Read an authorized invoice
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/purchases/:orderItemId/remove-access
Remove selected access under the supported policy
- Auth
- Account Bearer JWT
- 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.
POST
/api/library/redeem-serial
Customer serial claim; ownership proof still applies
- Auth
- Account Bearer JWT
- 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.
GET
/api/library/orders/:orderId/invoice.pdf
Customer-authorized order invoice
- Auth
- Account Bearer JWT
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- 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. 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. Shared library tokens follow their own token/ownership checks.
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.
Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED.
SoundSync
Rent-to-own test integration
Developer settings require workspace permissions; customer agreement operations require customer authentication. Production live checkout is explicitly unavailable.
GET
/api/developer/rent-to-own/settings
Read developer defaults
- Auth
- Account Bearer JWT
- 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.
PUT
/api/developer/rent-to-own/settings
Update defaults
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/products/:productId/rent-to-own
Read product override
- Auth
- Account Bearer JWT
- 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.
PUT
/api/developer/products/:productId/rent-to-own
Update product override
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/rent-to-own/preview
Preview the configured option
- Auth
- Account Bearer JWT
- 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.
GET
/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.
POST
/api/rent-to-own/checkout
Authenticated test checkout; production live requests rejected
- Auth
- Account Bearer JWT
- 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.
GET
/api/rent-to-own/customer/agreements
List the customer's agreements
- Auth
- Account Bearer JWT
- 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.
POST
/api/rent-to-own/customer/agreements/:agreementId/cancel
Cancel a permitted customer agreement
- Auth
- Account Bearer JWT
- 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
GET
/api/developer/products/catalog
Search the private developer catalog
- Auth
- Account Bearer JWT
- 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.
POST
/api/developer/products/:productId/marketplace-assets/render-preview
Render a private image without saving
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/billing/invoices/:invoiceId/download.csv
Download the developer billing invoice CSV
- Auth
- Account Bearer JWT
- 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.
GET
/api/developer/billing/statements/:statementId/download.csv
Download the developer billing statement CSV
- Auth
- Account Bearer JWT
- 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