Catalog · API reference

8 endpoints.

POST /v1/products/batch
GET /v1/products
GET /v1/products/{product_id}
DELETE /v1/products/{product_id}
POST /v1/reindex
GET /v1/attributes
GET /v1/attributes/mapping
PUT /v1/attributes/mapping

POST/v1/products/batch

Upsert and delete products (max 1,000 per call, idempotent)

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	`header`	`string \| null`	no	Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$

Request body `application/json` `ProductBatchRequest`

Name	Type	Required	Description
`upsert`	`ProductIn-Input[]`	no
`delete`	`string[]`	no	Product ids to delete.
`replace_all`	`boolean`	no	Full sync: after this batch (with sync_id complete), delete products not sent.default false
`sync_id`	`string \| null`	no	Groups batches of one full sync.max length 64
`sync_complete`	`boolean`	no	default false

Responses

200Successful ResponseProductBatchResult

GET/v1/products

List products

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`cursor`	`query`	`string \| null`	no	max length 200
`limit`	`query`	`integer`	no	default 50 · min 1 · max 200
`q`	`query`	`string \| null`	no	max length 200

Responses

200Successful ResponsePage_ProductOut_

GET/v1/products/{product_id}

Get one product

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`product_id`	`path`	`string`	yes

Responses

200Successful ResponseProductOut

DELETE/v1/products/{product_id}

Delete one product

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`product_id`	`path`	`string`	yes
`Idempotency-Key`	`header`	`string \| null`	no	Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$

Responses

200Successful ResponseDeleted

POST/v1/reindex

Rebuild the search index from stored products (zero downtime)

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	`header`	`string \| null`	no	Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$

Request body `application/json` `ReindexRequest`

Name	Type	Required	Description
`mode`	`"full" \| "settings_only"`	no	default "full"
`reason`	`string \| null`	no	max length 200

Responses

202Successful ResponseAccepted

GET/v1/attributes

Attributes found in the catalog

Needs a key or a dashboard session

Responses

200Successful ResponseAttributeInfo[]

GET/v1/attributes/mapping

Attribute normalization mapping

Needs a key or a dashboard session

Responses

200Successful ResponseAttributeMapping

PUT/v1/attributes/mapping

Replace the attribute mapping (triggers a reindex)

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	`header`	`string \| null`	no	Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$

Request body `application/json` `AttributeMappingUpdate`

Name	Type	Required	Description
`items`	`AttributeMappingItem[]`	yes

Responses

200Successful ResponseAttributeMapping

Data shapes on this page

ProductBatchRequest

Upsert and delete in one call. Max 1,000 items in total. Same body again = no change (idempotent).

Name	Type	Required	Description
`upsert`	`ProductIn-Input[]`	no
`delete`	`string[]`	no	Product ids to delete.
`replace_all`	`boolean`	no	Full sync: after this batch (with sync_id complete), delete products not sent.default false
`sync_id`	`string \| null`	no	Groups batches of one full sync.max length 64
`sync_complete`	`boolean`	no	default false

ProductIn-Input

One product, as sent to POST /v1/products:batch (upsert).

Name	Type	Required	Description
`id`	`string`	yes	The store's own product id.min length 1 · max length 128
`name`	`object`	yes
`description`	`object`	no
`brand`	`string \| null`	no	max length 200
`model`	`string \| null`	no	max length 200
`sku`	`string \| null`	no	max length 200
`gtin`	`string \| null`	no	max length 50
`url`	`string \| null`	no	max length 2048
`image_url`	`string \| null`	no	max length 2048
`price`	`number \| string`	yes	min 0
`sale_price`	`number \| string \| null`	no	min 0
`currency`	`string`	yes	ISO 4217, e.g. USD, SAR, AED.pattern ^[A-Z]{3}$
`in_stock`	`boolean`	no	default true
`stock_qty`	`integer \| null`	no	min 0
`categories`	`CategoryRef[]`	no
`attributes`	`map<string, string \| integer \| number \| boolean \| string[]>`	no	Raw attributes as the store has them, e.g. {'Size': 'M', 'Color': 'Black'}.
`tags`	`string[]`	no
`popularity`	`number \| null`	no	Business signal, opt-in.min 0
`margin`	`number \| null`	no	Business signal, opt-in. Never shown.
`visible`	`boolean`	no	default true
`updated_at`	`string (date-time) \| null`	no
`extra`	`object`	no	Opaque. Returned as is.

CategoryRef

One category the product belongs to, with its full path from the root.

Name	Type	Required	Description
`id`	`string`	yes	min length 1 · max length 128
`path`	`object[]`	yes	Root first. Each level is {lang: name}.

ProductBatchResult

Name	Type	Required	Description
`upserted`	`integer`	yes
`unchanged`	`integer`	yes
`deleted`	`integer`	yes
`errors`	`ItemError[]`	no
`visible_within_s`	`number`	no	Upserts are searchable within this time.default 5

ItemError

Name	Type	Required
`id`	`string \| null`	no
`index`	`integer`	yes
`code`	`string`	yes
`message`	`string`	yes

Page_ProductOut_

Name	Type	Required	Description
`data`	`ProductOut[]`	yes
`next_cursor`	`string \| null`	no
`total`	`integer \| null`	no	Present when cheap to count.

ProductOut

Name	Type	Required
`id`	`string`	yes
`product`	`ProductIn-Output`	yes
`content_hash`	`string`	yes
`created_at`	`string (date-time)`	yes
`updated_at`	`string (date-time)`	yes
`indexed_at`	`string (date-time) \| null`	no

ProductIn-Output

One product, as sent to POST /v1/products:batch (upsert).

Name	Type	Required	Description
`id`	`string`	yes	The store's own product id.min length 1 · max length 128
`name`	`object`	yes
`description`	`object`	no
`brand`	`string \| null`	no	max length 200
`model`	`string \| null`	no	max length 200
`sku`	`string \| null`	no	max length 200
`gtin`	`string \| null`	no	max length 50
`url`	`string \| null`	no	max length 2048
`image_url`	`string \| null`	no	max length 2048
`price`	`string`	yes
`sale_price`	`string \| null`	no
`currency`	`string`	yes	ISO 4217, e.g. USD, SAR, AED.pattern ^[A-Z]{3}$
`in_stock`	`boolean`	no	default true
`stock_qty`	`integer \| null`	no	min 0
`categories`	`CategoryRef[]`	no
`attributes`	`map<string, string \| integer \| number \| boolean \| string[]>`	no	Raw attributes as the store has them, e.g. {'Size': 'M', 'Color': 'Black'}.
`tags`	`string[]`	no
`popularity`	`number \| null`	no	Business signal, opt-in.min 0
`margin`	`number \| null`	no	Business signal, opt-in. Never shown.
`visible`	`boolean`	no	default true
`updated_at`	`string (date-time) \| null`	no
`extra`	`object`	no	Opaque. Returned as is.

Deleted

Name	Type	Required	Description
`deleted`	`boolean`	no	default true
`id`	`string`	yes

ReindexRequest

Name	Type	Required	Description
`mode`	`"full" \| "settings_only"`	no	default "full"
`reason`	`string \| null`	no	max length 200

Accepted

Name	Type	Required	Description
`accepted`	`boolean`	no	default true
`job`	`Job \| null`	no

Job

A row of the shared `jobs` table. Poll GET /v1/jobs/{id} until status is terminal.

Name	Type	Required	Description
`id`	`string`	yes
`kind`	`"reindex" \| "import" \| "sync" \| "translate_backfill" \| "translate_writeback" \| "export" \| "data_export" \| "data_delete" \| "embed" \| "synonym_mining"`	yes
`status`	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`	yes
`progress`	`number`	no	default 0 · min 0 · max 1
`created_at`	`string (date-time)`	yes
`started_at`	`string (date-time) \| null`	no
`finished_at`	`string (date-time) \| null`	no
`result`	`object \| null`	no
`error`	`string \| null`	no

AttributeInfo

Name	Type	Required	Description
`raw_name`	`string`	yes
`canonical_name`	`string \| null`	no
`products`	`integer`	yes	How many products have it.
`sample_values`	`string[]`	no
`facet`	`boolean`	no	default false
`unit`	`string \| null`	no

AttributeMapping

Name	Type	Required	Description
`items`	`AttributeMappingItem[]`	yes
`updated_at`	`string (date-time) \| null`	no

AttributeMappingItem

Name	Type	Required	Description
`raw_name`	`string`	yes	max length 200
`canonical_name`	`string`	yes	max length 100
`unit`	`string \| null`	no	max length 20
`value_map`	`map<string, string>`	no	e.g. {"Med": "M", "Navy Blue": "Navy"}
`facet`	`boolean`	no	default true

AttributeMappingUpdate

Name	Type	Required	Description
`items`	`AttributeMappingItem[]`	yes

Parameters

Request body application/json ProductBatchRequest

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body application/json ReindexRequest

Responses

Responses

Responses

Parameters

Request body application/json AttributeMappingUpdate

Responses

Data shapes on this page

ProductBatchRequest

ProductIn-Input

CategoryRef

ProductBatchResult

ItemError

Page_ProductOut_

ProductOut

ProductIn-Output

Deleted

ReindexRequest

Accepted

Job

AttributeInfo

AttributeMapping

AttributeMappingItem

AttributeMappingUpdate

Request body `application/json` `ProductBatchRequest`

Request body `application/json` `ReindexRequest`

Request body `application/json` `AttributeMappingUpdate`