# Edit catalog items

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

## Items Edit

> Adds, updates or removes catalog items by ID.

```json
{"openapi":"3.1.0","info":{"title":"Batch - REST API","version":"2.9"},"tags":[{"name":"Catalogs"}],"servers":[{"url":"https://api.batch.com/{version}","description":"production","variables":{"version":{"default":"2.11","description":"Version of the API"}}}],"security":[{"rest_key":[]}],"components":{"securitySchemes":{"rest_key":{"type":"http","scheme":"bearer","description":"## API Key Authentication\n\nAuthentication is required in order to interact with Batch's APIs.\n\nBatch implements authentication using API Keys, that we call the \"REST API Key\".\nYou can find it on your dashboard.\n\nPlease make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would\neasily be extractable.\n\n### How to authenticate\n\nIn order to authenticate your requests, add your REST API Key in the `Authorization` header and prefix it by `Bearer`. Example: `Authorization: Bearer bcd38d9rfb38ra28`.\n"}},"parameters":{"HeaderProjectKey":{"in":"header","name":"X-Batch-Project","description":"The unique project key, identifying a project on the Batch platform","schema":{"type":"string"},"required":true}},"schemas":{"attributes":{"type":"object","description":"A map of attribute keys to values.\nKey rules:\n  - `url(...)` → value must be a valid URL\n  - `date(...)` → value must be RFC 3339 or Unix timestamp\n  - `^[a-z0-9_]+$` → regular attribute names\n","additionalProperties":{"oneOf":[{"type":"array","maxItems":15,"items":{"type":"string","maxLength":64}},{"type":"boolean"},{"type":"integer"},{"type":"number","format":"float"},{"type":"string","maxLength":10000},{"type":"string","format":"date-time"},{"type":"integer","format":"int64"},{"type":"string","format":"uri"}]}},"Error":{"type":"object","required":["error_message","error_code"],"properties":{"error_message":{"description":"A human readable error message","type":"string"},"error_code":{"description":"Error code","type":"string"}}}},"responses":{"401":{"description":"The Rest API Key is not valid for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Batch's services are under maintenance. Please try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"responses-asyncResponse":{"description":"If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an indexing token. <br/>Once you get your indexing token, you can use it to check the indexing state with the view action.\n","content":{"application/json":{"schema":{"type":"object","properties":{"indexing_token":{"type":"string"}}}}}}}},"paths":{"/catalogs/items/edit":{"post":{"operationId":"catalog_items_edit","summary":"Items Edit","description":"Adds, updates or removes catalog items by ID.","tags":["Catalogs"],"parameters":[{"$ref":"#/components/parameters/HeaderProjectKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Name of the catalog."},"items":{"type":"array","minItems":1,"maxItems":200,"description":"List of catalog items to add or remove.","items":{"type":"object","required":["action","id"],"properties":{"id":{"type":"string","description":"Unique identifier of the catalog item."},"action":{"type":"string","enum":["add","remove"],"description":"Action to perform on the catalog item."},"attributes":{"type":"object","$ref":"#/components/schemas/attributes"}}}}}}}}},"responses":{"202":{"$ref":"#/components/responses/responses-asyncResponse"},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}}}
```

### Rate Limiting

To ensure fair usage and platform stability, the `/catalogs/items/edit` endpoint is subject to rate limiting, following the [Token Bucket](https://en.wikipedia.org/wiki/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](https://doc.batch.com/developer/api/cep/..#request-headers-and-authentication).

### 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.

```json
{
  "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](https://doc.batch.com/developer/api/cep/catalogs/update "mention") 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.

```json
{"firstname": "Jane"}
```

#### Integer

Integer attributes are supported and can be *null*. Setting an integer to *null* completely removes this attribute from the item.

```json
{"age": 25}
```

#### Float

Float attributes are supported and can be *null*. Setting a float to *null* completely removes this attribute from the item.

```json
{"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).

```json
{
  "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

```json
{
  "url(product_image)": "https://batchstore/product/4729/image.png",
  "url(product_deeplink)": "myapp://path/to/content"
}
```

#### Boolean

Boolean attributes can be *true or false*.

```json
{
  "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.

```json
"interests": ["bikes","cinema"]
```

### Success

If the POST to the API endpoint is successful you will receive an **HTTP 202** confirmation and **a token**.

```json
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](https://doc.batch.com/developer/api/cep/catalogs/view) 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).