---
title: "Replace Items"
method: POST
path: "/catalogs/replace/items"
tags: ["Catalogs"]
---

# Replace Items

`POST /catalogs/replace/items`

**Beta.** Catalog replace is a Beta feature and can change. Send the `Batch-Beta: catalog-replace` header on each call.
<br/><br/>Adds a batch of items to the pending revision of an open session. The items have the same structure, validation, and rate limit as `/catalogs/items/edit`. The items are not visible to reads of the live catalog until you complete the replace.
<br/><br/>Send as many batches as necessary to load the full catalog. The pending revision starts empty, thus every item is an add. Send each item id only once per session. If you send the same id two times, the session becomes inconsistent and you cannot complete it.

## Headers

- `X-Batch-Project` string, required
- `Batch-Beta` string, required — Value of the `Batch-Beta` header. It is a comma-separated list of Beta contract flags. Thus one request can opt into more than one Beta contract at the same time (`first-flag, second-flag`). Flags are lowercase and case-sensitive, and the order does not matter. Batch rejects an unknown flag with a `400` on any endpoint. When a contract becomes generally available, Batch continues to accept its flag but the flag has no more effect. Thus you never need to remove it.

## Request body

- object
  - `replace_token` string, required — Token that `/catalogs/replace/start` returns.
  - `items` object[], required — List of catalog items to add to the pending revision.
    - `id` string, required — Unique identifier of the catalog item.
    - `action` 'add', required — Action to do on the catalog item. A replace accepts only `add`, because the pending revision starts empty.
    - `attributes` Attributes, required — A map of attribute keys to values. Key rules: - `url(...)` → value must be a valid URL - `date(...)` → value must be RFC 3339 or Unix timestamp - `^[a-z0-9_]+$` → regular attribute names

## Response `202`

Batch added the items to the pending revision. The items are not visible to reads of the live catalog until you complete the replace. Batch returns no indexing token, and the body is an empty JSON object. <br/>To see the indexing progress, read the `pending_replace` block of `/catalogs/view`.

- EmptyResponse

## Other responses

- `400` — The request is malformed
- `401` — The Rest API Key is not valid for this project
- `409` — The replace session is unknown or no longer open.
- `429` — Too Many Requests
- `500` — Unexpected error
- `503` — Batch's services are under maintenance. Please try again later

---

[API](https://skmtc.net/batch/apis/batch-rest-api.md) · [All operations](https://skmtc.net/batch/apis/batch-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/batch/batch-rest-api/revisions/ec696334ff35/schema)