Import products asynchronously (202; poll GET /v1/operations/:id)

post

https://apis.kentro.live/channel/v1/products/import

Scope: products:write, channel:write or admin.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.

Body Params

products

array of objects

required

length between 1 and 1000

Each document is exactly a POST /v1/products body; each is written on its own, in order.

products*

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or a legacy 24-hex id.

channelId

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

Sales channel id: a uuid, or a legacy 24-hex id.

adapterId

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

The sales-platform adapter (legacy activeAdapterId) holding externalId / externalGroupId, as an alternative to channelId: the identity's channel is the one using it.

externalId

string

length between 1 and 255

The channel's id: the VARIANT id order lines carry for a simple product; the product (group) id for a product with variants.

externalGroupId

string

length between 1 and 255

A simple product's channel product id, when the channel has one.

identities

array of objects

length ≤ 50

Further channel identities (one product known to several channels or adapters), merged into the references as the root identity is.

identities

type

enum

Default stock. A POST with variants makes the product a group container (type variants).

sku

string

length between 1 and 100

barcode

string

length between 1 and 100

barcodeFormat

enum

name

string

length ≤ 255

description

string

length ≤ 100000

shortDescription

string

length ≤ 10000

unitCost

length ≤ 24

^[0-9]{1,14}(\.[0-9]{1,8})?$

A non-negative decimal amount in currency units ("12.50"); numbers are accepted.

weight

object

Stored in oz; another unit is converted.

dimensions

object

requiresShipping

boolean

Default true.

skipInventoryTracking

boolean

Default false.

notTaxable

boolean

taxCode

string

length ≤ 50

lotNumberPolicy

enum

hsCode

string

length ≤ 20

countryOfOrigin

string

length between 2 and 2

externalIdentifiers

array of objects

length ≤ 50

Replaces the set.

externalIdentifiers

images

array of objects

length ≤ 50

Replaces the set.

images

metadata

object

Keys 1 to 100 characters, values up to 1000.

listings

array of objects

length ≤ 50

Upserted by channel: a field not sent keeps its stored value.

listings

components

array of objects

length ≤ 100

type composition only; replaces the set.

components

variantOptions

array of objects

length ≤ 10

variantOptions

variants

array of objects

length between 1 and 250

variants

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or a legacy 24-hex id.

externalId

string

length between 1 and 255

The integration's own id for the document, unique within its channel.

identities

array of objects

length ≤ 50

The variant's identities per channel or adapter; externalId alone is its identity on the root's holder.

identities

sku

string

length between 1 and 100

barcode

string

length between 1 and 100

barcodeFormat

enum

name

string

length ≤ 255

description

string

length ≤ 100000

shortDescription

string

length ≤ 10000

unitCost

length ≤ 24

^[0-9]{1,14}(\.[0-9]{1,8})?$

A non-negative decimal amount in currency units ("12.50"); numbers are accepted.

weight

object

Stored in oz; another unit is converted.

dimensions

object

requiresShipping

boolean

Default true.

skipInventoryTracking

boolean

Default false.

notTaxable

boolean

taxCode

string

length ≤ 50

lotNumberPolicy

enum

hsCode

string

length ≤ 20

countryOfOrigin

string

length between 2 and 2

externalIdentifiers

array of objects

length ≤ 50

Replaces the set.

externalIdentifiers

images

array of objects

length ≤ 50

Replaces the set.

images

metadata

object

Keys 1 to 100 characters, values up to 1000.

listings

array of objects

length ≤ 50

Upserted by channel: a field not sent keeps its stored value.

listings

options

object

This variant's option values ({ Size: 'M' }).

vendors

array of objects

length ≤ 50

The tenant's vendors this product is sourced from (by id or externalId). Replaces the set; [] clears it; absent keeps it.

vendors

onDuplicate

enum

What a POST does when the document already exists. Default 'update' (D7).

overwriteVariants

boolean

Default false. true removes the group variants this request does not name (scoped to the channel identity); a variant holding stock or history refuses the request.

skipEvents

array of objects

length ≤ 50

skipEvents

Headers

Idempotency-Key

string

length between 7 and 50

Any string of 7 to 50 characters that identifies this request (an order number, a webhook id). A retry with the same key and the same body answers the first result with Idempotent-Replayed: true; the same key with a different body is 422 idempotency_key_reused; a concurrent request with the same key is 409 in_progress with Retry-After. Recommended on every write.

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

202Default Response

400Default Response

403Default Response