--- openapi: 3.0.3 info: title: Braze REST API – Edit multiple catalog items description: 'Use this endpoint to edit multiple existing 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": patch: summary: Edit multiple catalog items description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `catalogs.update_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. 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 PATCH '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": { "$add": [ "Biscuits", "Coleslaw" ], "$remove": [ "French Fries" ] }, "Open_Time": "2021-09-03T09:03:19.967+00:00" }, { "id": "restaurant3", "City": "San Francisco", "Rating": 2, "Top_Dishes": [ "Buffalo Wings", "Philly Cheesesteak" ] } ] }' ``` **Note:** - The `Location` field uses the `geo` data type, which expects an array formatted as `[longitude, latitude]`. - The `$add` and `$remove` operators are only applicable to array type fields, and are only supported by PATCH endpoints. ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. ### 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. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `ids-not-strings` | Item IDs must be of type string. | | `ids-not-unique` | Item IDs must be unique in the request. | | `invalid-ids` | Item IDs can only include 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 `$`. | | `items-missing-ids` | Some items don't have item IDs. Check that each item has an item ID. | | `item-array-invalid` | `items` must be an array of objects. | | `items-too-large` | Item values can't exceed 5,000 characters. | | `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. | | `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 updated 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.update_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: patch_catalogs_catalog_name_items_patch_catalog_items_bulk tags: - Catalogs responses: '202': description: The request was accepted for asynchronous processing. The items are updated in the catalog. content: application/json: schema: $ref: '#/components/schemas/CatalogItemsBulkResponse' '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. 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: CatalogItemsBulkResponse: 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