Guide
Catalog Import API
Create, inspect, advance, review, and commit catalog jobs, then attach permitted private delivery files.
Developer account permissions
Use a developer account session, not a product credential or partner key. All calls require product-view access. New-catalog operations require product-create permission and all-products scope. Filling a target draft requires product-edit permission and access to that product; allowUpdates also requires edit permission.
Private delivery actions additionally require file-management permission and product access. Without file-management permission, the job response hides download links, export samples, and the delivery manifest. Discovery and copy operations only accept supported public or authorized sources.
SoundSync
Add the private files after reviewing the import
The delivery step lets you select multiple installers or archives and review their product matches. Its resume guidance applies to this importer; public promotional media and customer-authorized downloads remain separate workflows.
SoundSync
Bring an existing catalog into the product workflow
Start from a store URL, an export, or both, then review the products and media before saving drafts. The downloadable examples help prepare an export. This product-import workflow does not move customer passwords, payment methods or every account record.
SoundSync
Job lifecycle
/api/developer/catalog-imports
List the latest workspace import jobs
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- { jobs: [...] }; current list is limited to the latest 10 jobs.
- Notes
- Returns the latest 10 workspace jobs. Import access requires the appropriate create/edit scope.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports
Start an import
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- storeUrl: string
- mode: catalog | single
- targetId: integer
- export: string
- Returns
- 201 with the visible job and current status.
- Notes
- export is one CSV/TSV/XLSX/JSON multipart file up to 8 MB. Use a public authorized source URL or export. Imported products remain drafts; do not copy accounts, billing authority or consent implicitly.
Request, response and error reference
Request (application/json or multipart/form-data)
{
"type": "object",
"properties": {
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"catalog",
"single"
]
},
"targetId": {
"type": "integer",
"minimum": 1
},
"export": {
"type": "string",
"format": "binary"
}
},
"additionalProperties": true,
"anyOf": [
{
"required": [
"storeUrl"
]
},
{
"required": [
"export"
]
}
]
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id
Read a workspace-owned job
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Visible job, candidates, warnings, progress, and permitted results.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/advance
Advance the next bounded discovery step
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated visible job. The client drives subsequent steps.
- Notes
- Advances one browser-driven discovery step; polling the job alone does not drive all future discovery.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/mapping
Review export column mappings
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- mapping: object (required). Canonical product field to an existing export header.
- Returns
- Updated visible job.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"mapping": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Canonical product field to an existing export header."
}
},
"required": [
"mapping"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/retry-discovery
Retry supported discovery work
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job; inspect warnings and status before continuing.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/media
Copy a discovered image or audio asset
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- kind: images | audio (required)
- url: string (required)
- Returns
- { asset: ... }; allowed during review, before committing.
- Notes
- The URL must be an allowed candidate source. Only review-stage media is copied.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"images",
"audio"
]
},
"url": {
"type": "string"
}
},
"required": [
"kind",
"url"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/commit
Save reviewed products as drafts
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- confirmed: true (required)
- products: array (required)
- allowUpdates: boolean
- Returns
- Completed visible job with saved-product results; repeated completed commits return the job.
- Notes
- Copy selected media before committing. Published products are skipped; matching existing drafts requires explicit allowUpdates. A completed-job replay returns the existing result rather than republishing.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"confirmed": {
"const": true
},
"products": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"allowUpdates": {
"type": "boolean"
}
},
"required": [
"confirmed",
"products"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"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.
SoundSync
Start discovery
curl -X POST "$SOUNDSYNC_ORIGIN/api/developer/catalog-imports" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" \
-H "Content-Type: application/json" \
--data '{"storeUrl":"https://example.com/products/example","mode":"single"}'
SoundSync
Private delivery after draft creation
/api/developer/catalog-imports/:id/delivery-manifest
Match an export to completed import results
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- export: string (required)
- nameColumn: string
- linkColumns: string
- Returns
- Manifest with rows, direct links, productId, and exact/ambiguous/unmatched state; review every match.
- Notes
- linkColumns is a JSON-encoded array of export header names. Review exact, ambiguous and unmatched product matches before starting file imports.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"export": {
"type": "string",
"format": "binary"
},
"nameColumn": {
"type": "string"
},
"linkColumns": {
"type": "string"
}
},
"required": [
"export"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": [
"integer",
"null"
]
},
"name": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId
List delivery upload jobs for an imported product
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Upload job list.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"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
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId
Start a remote-file copy
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- url: string (required)
- Returns
- 202 with upload job; repeated source requests use the job/product/source identity.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
],
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/direct
Start or resume multipart delivery upload
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- filename: string (required)
- sizeBytes: integer (required)
- mimeType: string
- multipart: boolean
- fileFingerprint: string
- Returns
- 201 with job and upload-session instructions; catalog delivery forces multipart mode.
- Notes
- Catalog delivery forces multipart mode. The product must be part of this completed import and within the actor product scope.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"sizeBytes": {
"type": "integer",
"minimum": 1,
"maximum": 10000000000
},
"mimeType": {
"type": "string"
},
"multipart": {
"type": "boolean"
},
"fileFingerprint": {
"type": "string",
"pattern": "^v1:[a-f0-9]{64}$"
}
},
"required": [
"filename",
"sizeBytes"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/part
Prepare an allowed upload part
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- partNumber: integer (required)
- Returns
- Signed upload instructions; use the returned method, URL, and headers.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
}
},
"required": [
"partNumber"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"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
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/complete
Verify multipart completion and attachment
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job and attachment outcome; do not attach an incomplete file yourself.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/cancel
Cancel a multipart upload
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job state.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/local
Upload a supported buffered local file
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- file: string (required)
- Returns
- 201 with the local upload job.
- Notes
- Buffered uploads have a lower limit than direct multipart delivery. The current upload policy determines the returned limit.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
},
"required": [
"file"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId
Inspect an upload
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current authorized 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": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId/retry
Retry eligible failed delivery work
- Auth
- Account Bearer session token
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job; a remote import can restart from the source.
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.
SoundSync
Error handling
| HTTP status | Action |
|---|---|
| 400 | Correct the URL, export, mapping, product selection, price/type, or confirmation. |
| 403 / 404 | Check workspace, product assignments, permission, and job ownership; do not probe other accounts. |
| 409 | Refresh the job: work may be busy, the state changed, media is not copied, or a product match requires review. |
| 429 | Reuse an existing job or wait for the workspace import limit. |
| 500 | Preserve the job ID and inspect its current state before retrying. |
Examples and returned data
These examples describe the current request contract, not a seeded response fixture for every source website. Treat source copy and filenames as untrusted data. Keep private links, tokens, and full job payloads out of public issue reports.
