Batch upsert catalog objects
POST
/v2/catalog/batch-upsert
Creates or updates up to 10,000 target objects based on the provided list of objects.
The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.
To ensure consistency, only one update request is processed at a time per seller account.
While one (batch or non-batch) update request is being processed, other (batched and non-batched)
update requests are rejected with the 429 error code.
Request body
Example code
A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID).
If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects.
See Idempotency for more information.
A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request.
For each object, its updated_at field is ignored and replaced with a current timestamp, and its
is_deleted field must not be set to true.
To modify an existing object, supply its ID. To create a new object, use an ID starting
with #. These IDs may be used to create relationships between an object and attributes of
other objects that reference it. For example, you can create a CatalogItem with
ID #ABC and a CatalogItemVariation with its item_id attribute set to
#ABC in order to associate the CatalogItemVariation with its parent
CatalogItem.
Any #-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.
Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.
The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".
Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:
UTC: 2020-01-26T02:25:34Z
Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00