Edit catalog items
Use /catalogs/items/edit to edit a catalog item. A catalog can contain up to 2 million items.
Adds, updates or removes catalog items by ID.
The unique project key, identifying a project on the Batch platform
project_0664hxvwffvbpn278gxdyhsadddqgna6Name of the catalog.
productsOnce you get your indexing token, you can use it to check the indexing state with the view action.
POST /2.6/catalogs/items/edit HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Content-Type: application/json
Accept: */*
Content-Length: 241
{
"name": "products",
"items": [
{
"id": "CATALOG_ITEM_ID",
"action": "add",
"attributes": {
"product_name": "Sample Product",
"price": 19.99,
"tags": [
"summer",
"sale"
],
"launch_date": "2023-08-01T12:00:00Z",
"available": true,
"website": "https://example.com"
}
}
]
}{
"indexing_token": "eqRqTF7xFznYoG0MLs1sIqM1JhmhGLTZ7I5NtM5f"
}Rate Limiting
To ensure fair usage and platform stability, the /catalogs/items/edit endpoint is subject to rate limiting, following the Token Bucket algorithm:
Up to 5 requests per second are allowed.
Up to 1000 items updated per second are allowed.
If you exceed these limits, the API will respond with an HTTP 429 Too Many Requests error. When you receive this error, please wait a few seconds before retrying, as further attempts may continue to be rejected until your rate falls back within the allowed limits.
What constitutes one "update"? One update corresponds to the processing associated with a single item included in your request. For example, if a request contains data for 10 different items, it will consume 10 updates from your rate limit, regardless of the number of attributes updated for each individual item within that same request.
Request structure
Route
The Catalog API exposes a POST endpoint that allows to update items of an existing catalog:
/catalog/items/edit
You can update one or several items via this endpoint, within the limit of 200 items.
Headers and authentication
See Overview → Using Project APIs.
Update item
The body of the request must contain a valid JSON payload describing the update operations to execute for a set of given items and catalog.
{
"name": "MOVIES",
"items": [
{
"action": "add",
"id": "1",
"attributes": {
"title": "Squid Game",
"description": "Hundreds of cash-strapped players accept a strange invitation to compete in children's games.",
"cast": [
"Lee Jung-jae",
"Park Hae-soo",
"Wi Ha-jun"
]
}
},
{
"action": "remove",
"id": "2"
}
]
}Attributes
You can set custom attributes associated with your items, with a name and a value.
Key names should be made of letters, numbers or underscores ([a-z0-9_]). They cannot be longer than 30 characters and cannot contain uppercase characters.
The following value types are supported:
String
Integer
Float
Date
URL
Boolean
String arrays
String
String types attributes cannot be empty or over 10,000 characters, they can be null. Setting a string to null completely removes this attribute from the item.
{"firstname": "Jane"}Integer
Integer attributes are supported and can be null. Setting an integer to null completely removes this attribute from the item.
{"age": 25}Float
Float attributes are supported and can be null. Setting a float to null completely removes this attribute from the item.
{"level_progress": 25.5}Date
JSON does not support date natively. Therefore, we require additional information to identify an attribute as a date. This is achieved by wrapping the attribute key in the date() function.
Dates are accepted in TS format in seconds and RFC 3339 format (2012-08-12T22:30:05Z).
{
"date(promo_starts)": 1451642400,
"date(promo_ends)": "2012-08-12T22:30:05Z"
}URL
URL type is also supported. You will need to wrap the key name in the url() function.
Values must be valid URLs and no longer than 2048 characters:
A scheme is compulsory (myapp://, https://...)
:// is compulsory after the scheme
{
"url(product_image)": "https://batchstore/product/4729/image.png",
"url(product_deeplink)": "myapp://path/to/content"
}Boolean
Boolean attributes can be true or false.
{
"is_premium": false
}String arrays
Arrays of strings are supported. A string in an array cannot be longer than 64 chars. You cannot have more than 15 elements in an array of string.
"interests": ["bikes","cinema"]Success
If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and a token.
HTTP Status Code: 202
Response:
{
"indexing_token": "eqRqTF7xFznYoG0MLs1sIqM1JhmhGLTZ7I5NtM5f_xm6sVnl7bQiFmGLmkCRk_ssYO-hTpAFm1AXo9MMiBYQW3JAx-o9aVrsCsvhL3oZ2e5Dvb4pa6KRyzenOMgc5Vcb"
}Once you get your token, you can use it to check the indexing state of this update with the API.
Failure
If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.
Processing time
While the indexation of items is usually done in real time, we offer no guarantees. If you send a campaign right after the catalog item update, you might end up with stale items. A call to the view action with the indexing token replies with an APPLIED indexing state if the processing is finished (and IN_PROCESS if it is still ongoing).
Last updated
Was this helpful?