Bulk Partial Update Catalog Item

/data/v2/projects/{project_id}/catalogs/{catalog_id}/items/partial-update

Introduction

Bulk Partial Update Catalog Item API endpoint updates properties specified in the request. The already existing properties that are not specified will be kept intact. If the item with the given ID doesn't exist, a new item will be created only if the upsert flag is specified.

How it works

If the item already exists, all the properties will be replaced, not merged. If some items are faulty, and produce errors, they won't be updated. However, the entire request won't fail either, and other items with the correct structure will be updated. This means you can sync your catalogs faster, ensuring accurate information for things like discounts, prices, and stock availability.

The response contains a list with the same number and order of items as the request body. For each item, either a success or a failure is indicated. For example, if you send 10 items, a body containing 10 elements will be returned, with the order matching the request. If you had an error in the 5th item, you would know this since the 5th item in the response will contain an error description:

[
...
{
    "success" : "False",
    "queued" : "False",
    "errors": {
        "properties": {
            Fields ['device_id'] are not properly defined.
        },
    }
}
...
]

Definition

Authorization

In this API call, you must use the following authorization access and permissions:

Available access typePermissions needed
Private accessCatalogs > Create or update catalog item

Read more about:

Path parameters

ParameterTypeDescriptionRequired
catalog_idstringThe ID of the desired existing catalog.Required
project_idstringThe ID of your project.Required

Item update attributes

ParameterTypeDescriptionRequired
propertiesobjectSpecify the item's properties in the catalog's fields. These need to be in the catalog definition and a value:key format, such as:

"properties": { "name": "iMac", "manufacturer": "Apple", ... }

Note that it is not possible to create new fields this way.
Required
item_idstringThe ID of the desired item within an existing catalog.

Note that due to the way the endpoint is decomposed, edits using API will only work with itemIds NOT containing /.
Required
upsertbooleanDefaults to false, if not present.No

🚧

Date field format

Catalog fields with Date data-type only accepts UNIX timestamps via API.

Header

ParameterTypeDescriptionRequired
authorizationstringUsed for authentication. Read more in the Authentication section.Required
content-typestringapplication/jsonRequired

Example response

HTTP/1.1 200 OK
        Content-Type: application/json

        [
            {
                "success" : "True",
                "queued" : "True",
            },
            {
                "success" : "True",
                "queued" : "True",
            },
            {
                "success" : "False",
                "queued" : "False",
                "errors": {
                    "properties": [
                        "Fields ['price_discounted'] are not properly defined."
                    ],
                }
            },
        ]

📘

Asynchronous endpoint

Note that this endpoint is asynchronous, which means that success response means only that the request is queued to be processed later, not that the item was successfully updated.

Limitations

  • The JSON request body must not exceed 10 MB of the payload size. This limit was determined based on the average catalog size of 21 fields. If there are more fields or longer content in the update items, the count must be below 5000.
  • Each request must not be larger than 5,000 items.
  • You can only send 5 requests per 10 seconds per catalog. This limitation covers both Bulk endpoints (Bulk Update Catalog Item and Bulk Partial Update Catalog Item, meaning that if you send, for instance, 2 update and 3 partial update requests within 10 seconds, you will hit the 5-requests limit.

Error conditions

Global

Status 400 with an error message is returned in these cases:

  • Invalid JSON
  • Payload not a list
  • Payload size exceeded
  • Too many items
  • Item parsing error

Per item

The status code is 200, but the update of individual items might have failed for the following reasons:

  • Malformed item structure
  • Validation error
  • Field does not exist
  • Item does not exist (only applies to upsert: false)
Language
Click Try It! to start a request and see the response here!