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
Job lifecycle
/api/developer/catalog-imports
List the latest workspace import jobs
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- { jobs: [...] }; current list is limited to the latest 10 jobs.
/api/developer/catalog-imports
Start an import
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- JSON or multipart fields: storeUrl; mode: catalog or single; optional targetId.
- Optional multipart file named export: CSV, TSV, XLSX, or JSON, up to 8 MB. A URL or export is required.
- Returns
- 201 with the visible job and current status.
/api/developer/catalog-imports/:id
Read a workspace-owned job
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Visible job, candidates, warnings, progress, and permitted results.
/api/developer/catalog-imports/:id/advance
Advance the next bounded discovery step
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated visible job. The client drives subsequent steps.
/api/developer/catalog-imports/:id/mapping
Review export column mappings
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- mapping: object mapping canonical product fields to existing header names.
- Returns
- Updated visible job.
/api/developer/catalog-imports/:id/retry-discovery
Retry supported discovery work
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job; inspect warnings and status before continuing.
/api/developer/catalog-imports/:id/media
Copy a discovered image or audio asset
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- kind: images or audio; url: one of the candidate source URLs.
- Returns
- { asset: ... }; allowed during review, before committing.
/api/developer/catalog-imports/:id/commit
Save reviewed products as drafts
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- confirmed: true; products: 1-200 selected candidates.
- Each product uses key, name, description, price, type, and selected images/audio/video URLs.
- allowUpdates: true explicitly permits filling missing fields in existing drafts. Copy selected images/audio first.
- Returns
- Completed visible job with saved-product results; repeated completed commits return the job.
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
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- multipart export; optional nameColumn; linkColumns as a JSON-encoded array of header names.
- Returns
- Manifest with rows, direct links, productId, and exact/ambiguous/unmatched state; review every match.
/api/developer/catalog-imports/:id/delivery/:productId
List delivery upload jobs for an imported product
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Upload job list.
/api/developer/catalog-imports/:id/delivery/:productId
Start a remote-file copy
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- url: authorized direct downloadable source.
- Returns
- 202 with upload job; repeated source requests use the job/product/source identity.
/api/developer/catalog-imports/:id/delivery/:productId/direct
Start or resume multipart delivery upload
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- filename, sizeBytes, mimeType; optional fileFingerprint (v1: plus 64 lowercase hexadecimal characters).
- Returns
- 201 with job and upload-session instructions; catalog delivery forces multipart mode.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/part
Prepare an allowed upload part
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- partNumber: requested positive part number.
- Returns
- Signed upload instructions; use the returned method, URL, and headers.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/complete
Verify multipart completion and attachment
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job and attachment outcome; do not attach an incomplete file yourself.
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/cancel
Cancel a multipart upload
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job state.
/api/developer/catalog-imports/:id/delivery/:productId/local
Upload a supported buffered local file
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- multipart file; buffered upload limits are lower than the large direct-upload path.
- Returns
- 201 with the local upload job.
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId
Inspect an upload
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current authorized job.
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId/retry
Retry eligible failed delivery work
- Auth
- Authenticated developer session
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job; a remote import can restart from the source.
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.