Edit catalog items

Use /catalogs/items/edit to edit a catalog item. A catalog can contain up to 2 million items.

Items Edit

post

Adds, updates or removes catalog items by ID.

Authorizations

rest_key

AuthorizationstringRequired

API Key Authentication

Authentication is required in order to interact with Batch's APIs.

Batch implements authentication using API Keys, that we call the "REST API Key". You can find it on your dashboard.

Please make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would easily be extractable.

How to authenticate

In order to authenticate your requests, add your REST API Key in the Authorization header and prefix it by Bearer. Example: Authorization: Bearer bcd38d9rfb38ra28.

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Body

application/json

namestringRequired

Name of the catalog.

Example: products

Responses

202

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an indexing token. Once you get your indexing token, you can use it to check the indexing state with the view action.

application/json

401

The Rest API Key is not valid for this project

application/json

429

Too Many Requests

application/json

500

Unexpected error

application/json

503

Batch's services are under maintenance. Please try again later

application/json

post

/catalogs/items/edit

HTTPcURLJavaScriptPython

POST /2.8/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: 252

{
  "name": "products",
  "items": [
    {
      "id": "CATALOG_ITEM_ID",
      "action": "add",
      "attributes": {
        "product_name": "Sample Product",
        "price": 19.99,
        "tags": [
          "summer",
          "sale"
        ],
        "date(launch_date)": "2023-08-01T12:00:00Z",
        "available": true,
        "url(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"
    }
  ]
}

• All attributes provided in the request must already exist in the catalog schema. Otherwise, the request will result in an error. (See the Update catalog documentation to learn more about adding or removing fields from a catalog schema.)

• Attributes that are omitted from the request will be ignored and left unchanged in the catalog.

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 [e-mail] 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).