Product Catalog · Push API

Push API Reference

Every operation of the push API at https://catalog.usethrottle.dev/v1/catalog, rendered from its OpenAPI document. Every route except the document itself takes a secret key as a bearer token: a store key (pc_sk_), or a vendor key (pc_vk_) on the operations that list it.

Download the OpenAPI document

Meta

This document.

GET /v1/catalog/openapi.json No key

This document.

No key
Implementation details

Operation getPushOpenApi.

Headers

FieldTypeRequiredDescription
If-None-MatchstringNoAn ETag of an earlier answer: 304 when it still matches.

Responses

200 OK. Headers: ETag.

Response fields

FieldTypeRequiredDescription
openapistringYes
304 Not modified: the answer still matches If-None-Match. Headers: ETag.

Jobs

Sync jobs: stage many batches, then close the job to apply them together.

POST /v1/catalog/jobs Server-side

Open a sync job: a staged, all-or-nothing push of many batches.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation openPushJob. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Request body

FieldTypeRequiredDescription
modestringNo
Values: merge, replace
fullSyncbooleanNo

Responses

201 Created.

Response fields

FieldTypeRequiredDescription
jobPushJobYes
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
409 Conflict with the state of the job, run or catalog, or with an earlier request.
413 Request body too large.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.open()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

POST /v1/catalog/jobs/{jobId}/batches Server-side

Stage a batch of rows in an open job (validated now, applied when the job closes).

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation sendPushJobBatch. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.
Idempotency-KeystringNoRequired when a row has quantityMode: "adjust" (a repeat would count twice); otherwise optional. A retry with the same key answers the first request again. Length 1–200

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Query parameters

FieldTypeRequiredDescription
profilestringNoThe name of a saved products mapping profile: the rows are mapped on arrival. Length at least 1

Request body

FieldTypeRequiredDescription
rowsPushRow | object[]YesItems 1–1000

Responses

202 Accepted: the work continues after the answer. Headers: Idempotent-Replayed.

Response fields

FieldTypeRequiredDescription
batchIdstringYesLength at least 1
sequenceintegerYes
rowsAcceptedintegerYes
rowsRefusedintegerYes
issuesobject[]YesItems at most 1000
issues[].indexintegerYes
issues[].codestringYes
Values: INVALID_ROW, INVALID_VALUE, MISSING_SKU, MISSING_PRODUCT_HANDLE, UNKNOWN_SKU, INVALID_GTIN_DROPPED, DUPLICATE_SKU_REPLACED, SCATTERED_PRODUCT_ROWS, CONFLICTING_PRODUCT_VALUE, PRODUCT_SPLIT_ACROSS_CHUNKS, TOO_MANY_OPTIONS, TOO_MANY_VARIANTS, CATEGORY_TOO_DEEP, INVALID_STATUS, IMAGE_COPY_FAILED, IMAGE_ONLY_ROW, INVALID_CURRENCY, PRICE_LIST_BASE_CURRENCY, LIST_SALE_WITHOUT_PRICE, LOCALE_NOT_ENABLED, GROUP_NOT_FOUND, GROUP_KIND_MISMATCH, TRANSLATION_TOO_LONG, TRANSLATION_CONFLICT, UNKNOWN_PRODUCT_HANDLE, INVALID_RATING, REVIEW_DATE_IN_FUTURE, REVIEW_TEXT_INVALID, DUPLICATE_REVIEW, REVIEW_ROW_LIMIT, EXTERNAL_ID_REQUIRED, SKU_CONFLICT, FIELD_NOT_ALLOWED, ATTRIBUTE_UNKNOWN, HANDLE_TAKEN, MERCHANT_HOLD, QUANTITY_BELOW_ZERO, QUANTITY_OUT_OF_RANGE, STOCK_MODE_CONFLICT, DUPLICATE_SKU_IN_BATCH, QUANTITY_MODE_WITHOUT_QUANTITY
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
413 Request body too large: the limit is 5 MiB (5,242,880 bytes); the code is REQUEST_BODY_TOO_LARGE.
422 The request is well formed but cannot be done.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.send()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

POST /v1/catalog/jobs/{jobId}/close Server-side

Close a job: its staged batches are applied together.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation closePushJob.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
jobPushJobYes
202 Accepted: the work continues after the answer.

Response fields

FieldTypeRequiredDescription
jobPushJobYes
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.close()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/jobs/{jobId} Server-side

The job's progress view.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getPushJob.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Query parameters

FieldTypeRequiredDescription
includestringNoSet to batches to list each batch with its status.

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
jobPushJobYes
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.get()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/jobs/{jobId}/errors.csv Server-side

The job's error report as CSV.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getJobErrorsCsv.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Responses

200 OK.
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.errorsCsv()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/jobs/{jobId}/stock Server-side

Per-row stock results of the job, a page at a time.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getJobStockResults.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Query parameters

FieldTypeRequiredDescription
cursorstringNoThe nextCursor of the previous page. Length 1–100
limitintegerNoHow many to return, from 1 to 500. Value 1–500

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
rowsPushStockResult[]Yes
nextCursorstring | nullYes
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.stockResults()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/jobs/{jobId}/stock.csv Server-side

Every stock result of the job as CSV.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getJobStockCsv.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
jobIdstringYesThe id of the job. Length at least 1

Responses

200 OK.
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.jobs.stockCsv()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

Batches

One batch of rows pushed as a run.

POST /v1/catalog/variants Server-side

Push one batch of rows as a run (a vendor key: an implicit one-batch job).

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation pushVariants. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.
Idempotency-KeystringNoRequired when a row has quantityMode: "adjust" (a repeat would count twice); otherwise optional. A retry with the same key answers the first request again. Length 1–200

Query parameters

FieldTypeRequiredDescription
modestringNoA vendor key only: merge, or replace to drop the vendor product fields the rows leave out.
Values: merge, replace
profilestringNoThe name of a saved products mapping profile: the rows are mapped on arrival. Length at least 1

Request body

FieldTypeRequiredDescription
rowsobject | object[]YesItems 1–1000

Responses

202 Accepted: the work continues after the answer. Headers: Idempotent-Replayed.

Response fields

FieldTypeRequiredDescription
runIdstringYesLength at least 1
statusstringYes
Values: pending, running, completed, failed
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
413 Request body too large: the limit is 5 MiB (5,242,880 bytes); the code is REQUEST_BODY_TOO_LARGE.
422 The request is well formed but cannot be done.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.batches.send()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

Runs

Run progress, error reports and stock results.

GET /v1/catalog/runs/{runId} Server-side

A run's progress and counts.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getPushRun.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
runIdstringYesThe id of the run. Length at least 1

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
runobjectYes
run.runIdstringYesLength 1–100
run.originstringYes
Values: upload, api
run.uploadIdstring | nullYes
run.fileTypestringYes
Values: products, fitment, oem, supersessions, reviews
run.modestringYes
Values: upsert, full_sync
run.sourceNamestringYesLength at least 1
run.statusstringYes
Values: pending, running, completed, failed
run.rowsReadintegerYes
run.rowsAppliedintegerYes
run.rowsFailedintegerYes
run.rowsWarnedintegerYes
run.createdintegerYes
run.updatedintegerYes
run.unchangedintegerYes
run.reportRowsintegerYes
run.failureCodestring | nullYes
run.createdAtstringYes
run.updatedAtstringYes
run.finishedAtstring | nullYes
run.vendorIdstring | nullNo
run.pushModestringNo
Values: merge, replace
run.fullSyncbooleanNo
run.reportExpiresAtstring | nullNo
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.runs.get()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/runs/{runId}/errors.csv Server-side

The run's error report as CSV.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getRunErrorsCsv.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
runIdstringYesThe id of the run. Length at least 1

Responses

200 OK.
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.runs.errorsCsv()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/runs/{runId}/stock Server-side

Per-row stock results of the run, a page at a time.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getRunStockResults.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
runIdstringYesThe id of the run. Length at least 1

Query parameters

FieldTypeRequiredDescription
cursorstringNoThe nextCursor of the previous page. Length 1–100
limitintegerNoHow many to return, from 1 to 500. Value 1–500

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
rowsPushStockResult[]Yes
nextCursorstring | nullYes
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.runs.stockResults()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

GET /v1/catalog/runs/{runId}/stock.csv Server-side

Every stock result of the run as CSV.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation getRunStockCsv.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Path parameters

FieldTypeRequiredDescription
runIdstringYesThe id of the run. Length at least 1

Responses

200 OK.
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
410 The report has expired (REPORT_EXPIRED).
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.runs.stockCsv()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

Products

Read a caller's products; archive, restore, rename, assign.

GET /v1/catalog/products Server-side

One product by externalId, sku or handle, or a page of the caller's products.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation listPushProducts.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Query parameters

FieldTypeRequiredDescription
externalIdstringNoRead the product with this external id. Length 1–255
skustringNoRead the product that has this SKU. Length at least 1
handlestringNoRead the product with this handle. Length at least 1
cursorstringNoThe nextCursor of the previous page. Length 1–100
limitintegerNoHow many to return, from 1 to 100. Value 1–100

Responses

200 OK. One of 2 answer shapes.

Response fields

FieldTypeRequiredDescription
productPushProductNo
productsPushProduct[]No
nextCursorstring | nullNo
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.products.list()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

POST /v1/catalog/products/archive Server-side

Archive products (reversible for 30 days).

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation archivePushProducts. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Request body

FieldTypeRequiredDescription
productsPushProductRef[]YesItems 1–100

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
resultsobject[]Yes
results[].indexintegerYes
results[].statusstringYes
Values: assigned, done, archived, restored, unchanged, held, not_found
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
413 Request body too large.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.products.archive()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

POST /v1/catalog/products/restore Server-side

Restore archived products.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation restorePushProducts. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Request body

FieldTypeRequiredDescription
productsPushProductRef[]YesItems 1–100

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
resultsobject[]Yes
results[].indexintegerYes
results[].statusstringYes
Values: assigned, done, archived, restored, unchanged, held, not_found
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
413 Request body too large.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.products.restore()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

POST /v1/catalog/products/rename Server-side

Change a product's handle.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation renamePushProduct. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Request body

FieldTypeRequiredDescription
productPushProductRefYes
handlestringYesLength 1–255

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
productPushProductYes
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
409 Conflict with the state of the job, run or catalog, or with an earlier request.
413 Request body too large.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.products.rename()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

PUT /v1/catalog/products/vendor Server-side

Assign products to a vendor, or take them back (vendorId: null). Store key only.

Bearer pc_sk_…
Implementation details

Operation assignPushProductsVendor. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.

Request body

FieldTypeRequiredDescription
vendorIdstring | nullYes
productsPushProductRef[]YesItems 1–100

Responses

200 OK.

Response fields

FieldTypeRequiredDescription
resultsobject[]Yes
results[].indexintegerYes
results[].statusstringYes
Values: assigned, done, archived, restored, unchanged, held, not_found
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
404 Not found, or outside what this key may reach.
413 Request body too large.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

Inventory

Synchronous price, availability and stock updates.

PATCH /v1/catalog/inventory Server-side

Set or adjust prices, availability and stock by SKU, synchronously.

Bearer pc_sk_… or pc_vk_…
Implementation details

Operation updateInventory. The JSON request body is required.

Headers

FieldTypeRequiredDescription
AuthorizationstringYesBearer, then a store key (pc_sk_) or a vendor key (pc_vk_) where the operation allows it.
Idempotency-KeystringNoRequired when a row has quantityMode: "adjust" (a repeat would count twice); otherwise optional. A retry with the same key answers the first request again. Length 1–200

Request body

FieldTypeRequiredDescription
rowsobject | object[]YesItems 1–1000

Responses

200 OK. Headers: Idempotent-Replayed.

Response fields

FieldTypeRequiredDescription
resultsobject[]Yes
results[].skustring | nullYes
results[].statusstringYes
Values: updated, unchanged, not_found, invalid
results[].codestringNo
Values: QUANTITY_BELOW_ZERO, QUANTITY_OUT_OF_RANGE, QUANTITY_MODE_WITHOUT_QUANTITY, STOCK_MODE_CONFLICT, DUPLICATE_SKU_IN_BATCH
results[].messagestringNo
results[].quantityintegerNo
results[].sourceWinsbooleanNo
400 Invalid request: a malformed parameter, header or body (issues names each).
401 Missing, unknown or revoked key (AUTHENTICATION_FAILED).
403 Refused for this key (VENDOR_PAUSED, VENDOR_KEY_NOT_ALLOWED).
409 Conflict with the state of the job, run or catalog, or with an earlier request.
413 Request body too large: the limit is 1 MiB (1,048,576 bytes); the code is REQUEST_BODY_TOO_LARGE.
429 Rate limited or queue full: retry after Retry-After seconds. Headers: Retry-After.
500 Internal error.
503 Temporarily unavailable: retry after Retry-After seconds when present. Headers: Retry-After.

SDK coverage

@usethrottle/catalog/admin · Node.js 20+, server only

  • admin.inventory.set()

Experimental. The SDK sends the key and makes the Idempotency-Key for you.

Error codes

Every error answers the same envelope, with a stable error.code. These are all the codes the API returns, with their HTTP statuses and whether a retry can succeed.

error.codeHTTPRetryable
AUTHENTICATION_FAILED401No
VENDOR_PAUSED403No
VENDOR_KEY_NOT_ALLOWED403No
INVALID_REQUEST400No
IDEMPOTENCY_KEY_REQUIRED400No
NOT_FOUND404No
PROFILE_NOT_FOUND404No
VENDOR_NOT_FOUND404No
IDEMPOTENCY_CONFLICT409No
RUN_IN_PROGRESS409Yes
JOB_CLOSED409No
JOB_FULL409No
TOO_MANY_OPEN_JOBS409Yes
REPORT_TOO_LARGE409No
HANDLE_TAKEN409No
IDENTIFIER_LOCKED409No
REPORT_EXPIRED410No
REQUEST_BODY_TOO_LARGE413No
MAPPING_INVALID422No
RATE_LIMITED429Yes
PUSH_QUEUE_FULL429Yes
INTERNAL_ERROR500Yes
INFRASTRUCTURE_UNAVAILABLE503Yes