--- openapi: 3.0.3 info: title: Braze REST API – Create catalog selection description: 'Use this endpoint to create a selection 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}/selections": post: summary: Create catalog selection description: | > Use this endpoint to create a selection in your catalog. ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `catalogs.create_selection` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all asynchronous catalog fields and selections 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 | | ----------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `selection` | Required | Object | An object that contains selection criteria. See [catalog selection object]({{site.baseurl}}/api/objects_filters/catalog_selection_object/) for a full breakdown of the object and its fields. | ### Selection object parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | | ---------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | Required | String | The name of the catalog selection. | | `description` | Optional | String | A description of the catalog selection. | | `external_id` | Optional | String | A unique identifier for the selection. | | `source` | Optional | String | The source of the catalog data. For Shopify catalogs, set this to `"Shopify"`. Accepted values are `"Shopify"` and `"Braze"`. | | `source` | Optional | String | The source of the catalog data. For Shopify catalogs, use `"Shopify"`. Accepted values are `"Shopify"` and `"Braze"`. | | `filters` | Required | Array | An array of filter objects to apply to the catalog items. You can specify up to ten filters per request. If an empty array of filters is provided, all items from the catalog are included. | | `results_limit` | Required | Integer | The maximum number of results to return. Must be a number between 1 and 50. | | `sort_field` | Optional | String | The field to sort results by. This must be paired with `sort_order`. If both `sort_field` and `sort_order` are not present, the results are randomized. | | `sort_order` | Optional | String | The order to sort results. Accepted values are `"asc"` (ascending) or `"desc"` (descending). This must be paired with `sort_field`. If both `sort_field` and `sort_order` are not present, the results are randomized. | **Note:** The `sort_field` and `sort_order` parameters must be used together. If you provide one without the other, or if you omit both parameters, the selection results are returned in a randomized order. ## Example Request The following sample request shows an example of how to create catalog selection. ``` curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/selections' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "selection": { "name": "favorite-restaurants", "description": "Favorite restaurants in NYC", "external_id": "favorite-nyc-restaurants", "filters": [ { "field": "City", "operator": "equals", "value": "NYC" }, { "field": "Rating", "operator": "greater than", "value": 7 } ], "results_limit": 10, "sort_field": "Rating", "sort_order": "desc" } }' ``` ### Filter operators The following table provides more details for this section. | Field type | Supported operators | | ---------- | ------------------------------------------------------- | | `string` | `equals`, `does not equal` | | `number` | `equals`, `does not equal`, `greater than`, `less than` | | `boolean` | `is` | | `time` | `before`, `after` | | `array` | `includes value`, `does not include value` | | `geo` | `geo within`, `geo outside` | **Note:** The API supports a maximum of ten filters per selection request. Filters are applied in the order they appear in the array. **Note:** When you apply a `geo` filter, the system automatically sorts results by distance with the nearest item first, regardless of the `sort_field` and `sort_order` parameters. ## 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": "catalog-not-found", "message": "Could not find catalog", "parameters": [ "catalog_name" ], "parameter_values": [ "restaurants" ] } ], "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. | | `selection-limit-reached` | The catalog selections limit is reached. | | `invalid-selection` | Check that the selection is valid. | | `too-many-filters` | Check if the selection has too many filters. | | `selection-name-already-exists` | Check if the selection name already exists in the catalog. | | `selection-has-invalid-filter` | Check if the selection filter is valid. | | `selection-invalid-results-limit` | Check if the selection results limit is valid. | | `invalid-sorting` | Check if the selection sorting is valid. | | `invalid-sort-field` | Check if the selection sort field is valid. | | `invalid-sort-order` | Check if the selection sort order is valid. | | `selection-contains-too-many-arrays` | Check if the selection contains more than one field with `array` type. Only one is supported. | ## 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 selection is created. | `success` | No action needed. | | `400 Bad Request` | The request body is missing the `selection` object. | `The selection is invalid. Field 'selection' is missing from the request.` | Include a `selection` object. | | `400 Bad Request` | A selection field has the wrong type. | `The selection is invalid. Field 'name' and 'description' must contain strings. Field 'filters' must be an array.` | Send `name`/`description` as strings and `filters` as an array. | | `400 Bad Request` | A selection with this name already exists. | `The selection name is already in use.` | Use a unique selection name. | | `400 Bad Request` | The selection has too many filters. | `Too many filters. Filters should not exceed the maximum.` | Reduce the number of filters. | | `400 Bad Request` | The `sort` order isn't `asc` or `desc`. | `The sort order can only be 'asc' or 'desc'.` | Set the sort order to `asc` or `desc`. | | `400 Bad Request` | The catalog reached its selections limit. | `The catalog has reached its selections limit` | Delete unused selections before creating new ones. | | `400 Bad Request` | The catalog is still processing a previous change. | `The catalog is processing. Please try again later.` | Wait for processing to finish, then retry. | | `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.create_selection` 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: post_catalogs_catalog_name_selections_post_create_catalog_selections tags: - Catalogs responses: '202': description: The request was accepted for asynchronous processing. The selection is created. content: application/json: schema: $ref: '#/components/schemas/CreateCatalogSelectionsResponse' '400': description: |- Bad Request. Causes include: - `The selection is invalid. Field 'selection' is missing from the request.` — The request body is missing the `selection` object. - `The selection is invalid. Field 'name' and 'description' must contain strings. Field 'filters' must be an array.` — A selection field has the wrong type. - `The selection name is already in use.` — A selection with this name already exists. - `Too many filters. Filters should not exceed the maximum.` — The selection has too many filters. - `The sort order can only be 'asc' or 'desc'.` — The `sort` order isn't `asc` or `desc`. - `The catalog has reached its selections limit` — The catalog reached its selections limit. - `The catalog is processing. Please try again later.` — The catalog is still processing a previous change. 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: - selection properties: selection: type: object description: An object that contains selection criteria. See catalog selection object for a full breakdown of the object and its fields. required: - name - filters - results_limit properties: name: type: string description: The name of the catalog selection. description: type: string description: A description of the catalog selection. external_id: type: string description: A unique identifier for the selection. source: type: string description: The source of the catalog data. For Shopify catalogs, use `"Shopify"`. Accepted values are `"Shopify"` and `"Braze"`. filters: type: array description: An array of filter objects to apply to the catalog items. You can specify up to ten filters per request. If an empty array of filters is provided, all items from the catalog are included. items: type: object required: - field - operator - value properties: field: type: string description: The catalog field to filter on. operator: type: string description: The comparison to apply. See the filter operators table for the operators each field type supports. value: description: The value to compare the field against. The accepted type depends on the field and operator. results_limit: type: integer description: The maximum number of results to return. Must be a number between 1 and 50. sort_field: type: string description: The field to sort results by. This must be paired with `sort_order`. If both `sort_field` and `sort_order` are not present, the results are randomized. sort_order: type: string description: The order to sort results. Accepted values are `"asc"` (ascending) or `"desc"` (descending). This must be paired with `sort_field`. If both `sort_field` and `sort_order` are not present, the results are randomized. parameters: - name: catalog_name in: path required: true description: Path parameter `catalog_name`. schema: type: string components: schemas: CreateCatalogSelectionsResponse: 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