--- openapi: 3.0.3 info: title: Braze REST API – Edit catalog item description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `catalogs.update_item` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). 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/{item_id}": patch: summary: Edit catalog item operationId: patch_catalogs_catalog_name_items_item_id_patch_catalog_item parameters: - name: catalog_name in: path required: true description: Name of the catalog. schema: type: string example: restaurants - name: item_id in: path required: true description: The ID of the catalog item. schema: type: string maxLength: 250 pattern: '^[A-Za-z0-9_-]+$' example: restaurant1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EditCatalogItemRequest' examples: restaurant: summary: Edit a restaurant item value: items: - 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" responses: "200": description: The request succeeded and the catalog item was updated. No action needed. content: application/json: schema: $ref: '#/components/schemas/CatalogItemResponse' examples: success: summary: Item updated value: message: success "400": description: | Bad request. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. To resolve it: - **The request body includes an `id`, which isn't allowed here (`id-in-body`):** Send the item `id` in the URL, not the body. - **The request references fields that don't exist in the catalog (`invalid-fields`):** Only use fields defined on the catalog, or add them first. Confirm that the fields in the request exist in the catalog. - **An item value exceeds the maximum length (`items-too-large`):** Shorten the flagged item values. Character limit for each item is 5,000 characters. - **A value can't be converted to the field's type (`unable-to-coerce-value`):** Send values that match each field's type. Item types can't be converted. - **`arbitrary-error`:** An arbitrary error occurred. Please try again or contact [Support]({{site.baseurl}}/support_contact/). - **`filtered-set-field-too-long`:** The field value is being used in a filtered set that exceeds the character limit for an item. - **`ids-too-large`:** Character limit for each item ID is 250 characters. - **`invalid-ids`:** Supported characters for item ID names are letters, numbers, hyphens, and underscores. - **`invalid-keys-in-value-object`:** Item object keys can't include `.` or `$`. - **`items-array-is-invalid`:** `items` must be an array of objects. - **`request-includes-too-many-items`:** You can only edit one catalog item per request. - **`too-deep-nesting-in-value-object`:** Item objects can't have more than 50 levels of nesting. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: id_in_body: summary: Item ID in the request body value: errors: - id: id-in-body message: "'id' can't be included in this request's body" parameters: [] parameter_values: [] message: Invalid Request invalid_fields: summary: Fields that don't exist in the catalog value: errors: - id: invalid-fields message: Some of the fields given do not exist in the catalog parameters: - id parameter_values: - restaurant1 message: Invalid Request items_too_large: summary: Item value too long value: errors: - id: items-too-large message: There are item values that exceed 5000 characters parameters: - id - field parameter_values: - id: restaurant1 field: Name message: Invalid Request unable_to_coerce_value: summary: Value doesn't match the field type value: errors: - id: unable-to-coerce-value message: Unable to coerce value to correct type parameters: - id - field - type parameter_values: - id: restaurant1 field: Rating type: number message: Invalid Request arbitrary_error: summary: Arbitrary error value: errors: - id: arbitrary-error message: Something went wrong. Please try again or notify support parameters: - item_id parameter_values: - restaurant1 message: Invalid Request filtered_set_field_too_long: summary: Field value too long for a selection value: errors: - id: filtered-set-field-too-long message: Field value is too long due to it being used in a selection. parameters: - field parameter_values: - Cuisine message: Invalid Request ids_too_large: summary: Item ID longer than 250 characters value: errors: - id: ids-too-large message: Item ids can not be larger than 250 characters parameters: - id parameter_values: - restaurant1_with_an_id_longer_than_250_characters message: Invalid Request invalid_ids: summary: Item ID with unsupported characters value: errors: - id: invalid-ids message: Item ids can only include letters, numbers, hyphens, and underscores parameters: - id parameter_values: - restaurant.1 message: Invalid Request invalid_keys_in_value_object: summary: Object key with `.` or `$` value: errors: - id: invalid-keys-in-value-object message: Item object keys can't include `.` or `$`. parameters: - id - field parameter_values: - id: restaurant1 field: Preferences message: Invalid Request item_array_invalid: summary: Items isn't an array of objects value: errors: - id: items-array-is-invalid message: The items array is invalid parameters: [] parameter_values: [] message: Invalid Request request_includes_too_many_items: summary: More than one item value: errors: - id: request-includes-too-many-items message: Request has too many items. The maximum is 1. parameters: [] parameter_values: [] message: Invalid Request too_deep_nesting_in_value_object: summary: Object nested more than 50 levels value: errors: - id: too-deep-nesting-in-value-object message: Item objects can't have more than 50 levels of nesting parameters: - id - field parameter_values: - id: restaurant1 field: Preferences message: Invalid Request "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `catalogs.update_item` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "404": description: | Not found. To resolve it: - **No item matches the `id` (`item-not-found`):** Pass a valid item `id`, or create the item first. Check that the item is in the catalog. - **No catalog matches the `catalog_name` (`catalog-not-found`):** Pass a valid `catalog_name`. Find it with the [List catalogs endpoint]({{site.baseurl}}/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs/). Check that the catalog name is valid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: item_not_found: summary: Item not found value: errors: - id: item-not-found message: Could not find item parameters: - item_id parameter_values: - restaurant1 message: Invalid Request catalog_not_found: summary: Catalog not found value: errors: - id: catalog-not-found message: Could not find catalog parameters: - catalog_name parameter_values: - restaurants message: Not Found "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: over_rate_limit: summary: Over rate limit value: message: You have exceeded your limit of 50 requests per minute. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/. 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key description: | REST API keys are created in the Braze dashboard at **Settings → APIs and Identifiers → API Keys**. The key must include the `catalogs.update_item` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: CatalogItem: title: Catalog item type: object additionalProperties: true description: | The item objects should contain fields that exist in the catalog except for the `id` field. **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. EditCatalogItemRequest: title: Edit catalog item request type: object required: [items] properties: items: type: array maxItems: 1 description: An array that contains item objects. The item objects should contain fields that exist in the catalog except for the `id` field. Only one item object is allowed per request. items: $ref: '#/components/schemas/CatalogItem' CatalogItemResponse: title: Edit catalog item response type: object properties: message: type: string example: success CatalogError: title: Catalog error type: object properties: id: type: string description: The error ID. See [Troubleshooting](#troubleshooting). example: invalid-fields message: type: string description: Human-readable error message. example: Some of the fields given do not exist in the catalog parameters: type: array description: Names of the request values that caused the error. items: type: string parameter_values: type: array description: Values of those parameters. For item field errors, each value is an object with the item `id`, the `field`, and sometimes the field `type`. items: anyOf: - type: string - type: object additionalProperties: true ErrorResponse: title: Error type: object properties: errors: type: array items: $ref: '#/components/schemas/CatalogError' message: type: string description: Human-readable error message.