--- openapi: 3.0.3 info: title: Braze REST API – Replace catalog items description: 'Use this endpoint to replace multiple items in your catalog. ' version: 1.0.0 contact: name: Braze Support url: https://www.braze.com/docs/braze_support/ license: name: Braze Documentation url: https://www.braze.com/docs/api/home/ servers: - url: https://rest.iad-01.braze.com description: US-01 - url: https://rest.iad-02.braze.com description: US-02 - url: https://rest.iad-03.braze.com description: US-03 - url: https://rest.iad-04.braze.com description: US-04 - url: https://rest.iad-05.braze.com description: US-05 - url: https://rest.iad-06.braze.com description: US-06 - url: https://rest.iad-07.braze.com description: US-07 - url: https://rest.iad-08.braze.com description: US-08 - url: https://rest.us-10.braze.com description: US-10 - url: https://rest.fra-01.braze.eu description: EU-01 - url: https://rest.fra-02.braze.eu description: EU-02 - url: https://rest.au-01.braze.com description: AU-01 - url: https://rest.id-01.braze.com description: ID-01 - url: https://rest.jp-01.braze.com description: JP-01 - url: https://rest.kr-01.braze.com description: KR-01 security: - BearerAuth: [] paths: "/catalogs/{catalog_name}/items": put: summary: Replace catalog items description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `catalogs.replace_items` permission. ## Rate limit This endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Path parameters The following table lists the path parameters for this endpoint. | Parameter | Required | Data Type | Description | |---|---|---|---| | `catalog_name` | Required | String | Name of the catalog. | ## Request parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | |---|---|---|---| | `items` | Required | Array | An array that contains item objects. Each object must have an ID. The item objects should contain fields that exist in the catalog. Up to 50 item objects are allowed per request. | ## Example request ``` curl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ { "id": "restaurant1", "Name": "Restaurant", "Loyalty_Program": false, "Location": [-73.988103, 40.779109], "Preferences": { "favorite_brand": "Nike", "shirt_size": "L" }, "Top_Dishes": [ "Hamburger", "Deluxe Cheeseburger" ], "Open_Time": "2021-09-03T09:03:19.967+00:00" }, { "id": "restaurant3", "City": "San Francisco", "Rating": 2, "Top_Dishes": [ "Hot Dog", "French Fries" ] } ] }' ``` **Note:** The `Location` field uses the `geo` data type, which expects an array formatted as `[longitude, latitude]`. ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. **Note:** The system can also return a `400` response if your company has reached its catalog storage limit. The free version of catalogs is capped at 500 MB. For more information about storage tiers and how to upgrade, see [Data storage limitations]({{site.baseurl}}/user_guide/data/activation/catalogs#data-storage-limitations). ### Example success response The status code `202` could return the following response body. ```json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ { "id": "invalid-fields", "message": "Some of the fields given do not exist in the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant1" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `company-size-limit-already-reached` | The catalog storage size limit is reached. To learn about storage tiers, see [Data storage limitations]({{site.baseurl}}/user_guide/data/activation/catalogs#data-storage-limitations). | | `company-size-limit-surge` | The request exceeds your company's remaining catalog storage. Try again with a smaller update. To learn about storage tiers, see [Data storage limitations]({{site.baseurl}}/user_guide/data/activation/catalogs#data-storage-limitations). | | `ids-not-string` | Confirm that each item ID is a string. | | `ids-not-unique` | Check that each item ID is unique. | | `ids-too-large` | Character limit for each item ID is 250 characters. | | `item-array-invalid` | `items` must be an array of objects. | | `items-missing-ids` | Some items don't have item IDs. Confirm that each item has an ID. | | `items-too-large` | Item values can't exceed 5,000 characters. | | `invalid-ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `invalid-fields` | Confirm that all fields you are sending in the API request already exist in the catalog. This is not related to the ID field mentioned in the error. | | `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. | | `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. | | `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `unable-to-coerce-value` | Item types can't be converted. | ## Response status codes The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it. | Status code | Meaning | Error message | How to resolve | | --- | --- | --- | --- | | `202 Accepted` | The request was accepted for asynchronous processing. The items are replaced in the catalog. | `success` | No action needed. | | `400 Bad Request` | The `items` value isn't a valid array. | `The items array is invalid` | Pass `items` as an array of item objects. | | `400 Bad Request` | The request includes more than 50 items. | The items array is invalid. | Send 50 or fewer items per request. | | `400 Bad Request` | The request references fields that don't exist in the catalog. | `Some of the fields given do not exist in the catalog` | Only use fields defined on the catalog, or add them first. | | `400 Bad Request` | The request includes duplicate item IDs. | `Item ids are not unique in the request` | Make every item `id` unique within the request. | | `400 Bad Request` | An item value exceeds the maximum length. | `There are item values that exceed the maximum length` | Shorten the flagged item values. | | `400 Bad Request` | A value can't be converted to the field's type. | `Unable to coerce value to correct type` | Send values that match each field's type. | | `404 Not Found` | No catalog matches the `catalog_name`. | `Could not find catalog` | Pass a valid `catalog_name`. Find it with the [List catalogs endpoint]({{site.baseurl}}/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs/). | | `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). | | `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `catalogs.replace_items` permission. | | `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). | | `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). | operationId: put_catalogs_catalog_name_items_put_update_catalog_items tags: - Catalogs responses: '202': description: The request was accepted for asynchronous processing. The items are replaced in the catalog. content: application/json: schema: $ref: '#/components/schemas/UpdateCatalogItemsResponse' '400': description: |- Bad Request. Causes include: - `The items array is invalid` — The `items` value isn't a valid array. - The request includes more than 50 items. - `Some of the fields given do not exist in the catalog` — The request references fields that don't exist in the catalog. - `Item ids are not unique in the request` — The request includes duplicate item IDs. - `There are item values that exceed the maximum length` — An item value exceeds the maximum length. - `Unable to coerce value to correct type` — A value can't be converted to the field's type. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No catalog matches the `catalog_name`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The REST API key is missing, malformed, or sent to the wrong REST endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The REST API key doesn't have the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: You exceeded the rate limit for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '5XX': description: An unexpected error occurred on the Braze server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: required: true content: application/json: schema: type: object required: - items properties: items: type: array items: type: object description: An array that contains item objects. Each object must have an ID. The item objects should contain fields that exist in the catalog. Up to 50 item objects are allowed per request. parameters: - name: catalog_name in: path required: true description: Path parameter `catalog_name`. schema: type: string components: schemas: UpdateCatalogItemsResponse: type: object properties: message: type: string ErrorResponse: type: object properties: errors: type: array items: type: object properties: id: type: string message: type: string parameters: type: array items: type: string parameter_values: type: array items: type: string message: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key