<- Catalog API

Catalog API

All versions ->

Upsert catalog object

POST

 /v2/catalog/object

This endpoint uses full-replacement semantics. The client must send the complete object, and any field absent from the request is interpreted as an intentional clear. This logic applies to nested objects as well. For example, omitting inlined children like variations will delete them.

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.

Permissions:ITEMS_WRITE

Guide

Build a Simple Catalog

Try in API Explorer
Link to section

Request body

Example code

Link to section

idempotency_key

string

Required

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.

Min Length
1
Max Length
128
Link to section

object

Required

A CatalogObject to be created or updated.

  • For updates, the object must be active (the is_deleted field is not true).
  • For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID.
Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

catalog_object

The successfully created or updated CatalogObject.

Link to section

id_mappings

The mapping between client and server IDs for this upsert.

Error descriptions