BrazeEx.Api.CatalogsCatalogItemsSynchronous (braze_ex v1.0.22)

API calls for all endpoints tagged CatalogsCatalogItemsSynchronous.

Link to this section Summary

Functions

List Multiple Catalog Item Details

Use this endpoint to return multiple catalog items and their content.

Delete a Catalog Item

Use this endpoint to delete an item in your catalog.

List Catalog Item Details

Use this endpoint to return a catalog item and its content.

Edit Catalog Items

Use this endpoint to edit an item in your catalog.

Create Catalog Item

Use this endpoint to create an item in your catalog.

Update Catalog Item

Use this endpoint to update an item in your catalog.

Link to this section Functions

Link to this function

catalogs_catalog_name_items_get(connection, catalog_name, opts \\ [])

@spec catalogs_catalog_name_items_get(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Tesla.Env.t()}

list-multiple-catalog-item-details

List Multiple Catalog Item Details

Use this endpoint to return multiple catalog items and their content.

prerequisites

Prerequisites

To use this endpoint, you’ll need an API key with the catalogs.get_items permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.

query-parameters

Query parameters

Note that each call to this endpoint will return 50 items. For a catalog with more than 50 items, use the Link header to retrieve the data on the next page as shown in the following example response.

ParameterRequiredData TypeDescription
cursorOptionalStringDetermines the pagination of the catalog items.

example-requests

Example requests

without-cursor

Without cursor

curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY'

with-cursor

With cursor

curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items?cursor=c2tpcDow' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY'

response

Response

There are three status code responses for this endpoint: 200, 400, and 404.

example-success-response

Example success response

The status code 200 could return the following response header and body.

{% alert note %}
The Link header won't exist if the catalog has less than or equal to 50 items. For calls without a cursor, prev will not show. When looking at the last page of items, next will not show.
{% endalert %}

Link: ; rel="prev",; rel="next"
{
"items": [
  {
    "id": "restaurant1",
    "Name": "Restaurant1",
    "City": "New York",
    "Cuisine": "American",
    "Rating": 5,
    "Loyalty_Program": true,
    "Open_Time": "2022-11-02T09:03:19.967Z"
  },
  {
    "id": "restaurant2",
    "Name": "Restaurant2",
    "City": "New York",
    "Cuisine": "American",
    "Rating": 10,
    "Loyalty_Program": true,
    "Open_Time": "2022-11-02T09:03:19.967Z"
  },
  {
    "id": "restaurant3",
    "Name": "Restaurant3",
    "City": "New York",
    "Cuisine": "American",
    "Rating": 5,
    "Loyalty_Program": false,
    "Open_Time": "2022-11-02T09:03:19.967Z"
  }
],
"message": "success"
}

example-error-response

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

{
"errors": [
  {
    "id": "invalid-cursor",
    "message": "'cursor' is not valid",
    "parameters": [
      "cursor"
    ],
    "parameter_values": [
      "bad-cursor"
    ]
  }
],
"message": "Invalid Request"
}

troubleshooting

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps.

ErrorTroubleshooting
catalog-not-foundCheck that the catalog name is valid.
invalid-cursorCheck that your cursor is valid.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

catalogs_catalog_name_items_item_id_delete(connection, catalog_name, item_id, opts \\ [])

@spec catalogs_catalog_name_items_item_id_delete(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

delete-a-catalog-item

Delete a Catalog Item

Use this endpoint to delete an item in your catalog.

prerequisites

Prerequisites

To use this endpoint, you’ll need an API key with the catalogs.delete_item permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.
item_idRequiredStringThe ID of the catalog item.

request-parameters

Request parameters

There is no request body for this endpoint.

example-request

Example request

curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY'

response

Response

There are three status code responses for this endpoint: 202, 400, and 404.

example-success-response

Example success response

The status code 202 could return the following response body.

{
"message": "success"
}

example-error-response

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

{
"errors": [
  {
    "id": "item-not-found",
    "message": "Could not find item",
    "parameters": [
      "item_id"
    ],
    "parameter_values": [
      "restaurant34"
    ]
  }
],
"message": "Invalid Request"
}

troubleshooting

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps.

ErrorTroubleshooting
arbitrary-errorAn arbitrary error occurred. Please try again or contact Support.
catalog-not-foundCheck that the catalog name is valid.
item-not-foundCheck that the item to be deleted exists in your catalog.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • item_id (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

catalogs_catalog_name_items_item_id_get(connection, catalog_name, item_id, opts \\ [])

@spec catalogs_catalog_name_items_item_id_get(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

list-catalog-item-details

List Catalog Item Details

Use this endpoint to return a catalog item and its content.

prerequisites

Prerequisites

To use this endpoint, you’ll need an API key with the catalogs.get_item permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.
item_idRequiredStringThe ID of the catalog item.

request-parameters

Request parameters

There is no request body for this endpoint.

example-request

Example request

curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY'

response

Response

There are two status code responses for this endpoint: 200 and 404.

example-success-response

Example success response

The status code 200 could return the following response body.

{
"items": [
  {
    "id": "restaurant3",
    "Name": "Restaurant1",
    "City": "New York",
    "Cuisine": "American",
    "Rating": 5,
    "Loyalty_Program": true,
    "Open_Time": "2022-11-01T09:03:19.967Z"
  }
],
"message": "success"
}

example-error-response

Example error response

The status code 404 could return the following response. Refer to Troubleshooting for more information about errors you may encounter.

{
"errors": [
  {
    "id": "item-not-found",
    "message": "Could not find item",
    "parameters": [
      "item_id"
    ],
    "parameter_values": [
      "restaurant34"
    ]
  }
],
"message": "Invalid Request"
}

troubleshooting

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps, if applicable.

ErrorTroubleshooting
catalog-not-foundCheck that the catalog name is valid.
item-not-foundCheck that the item is in the catalog.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • item_id (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

catalogs_catalog_name_items_item_id_patch(connection, catalog_name, item_id, opts \\ [])

@spec catalogs_catalog_name_items_item_id_patch(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

edit-catalog-items

Edit Catalog Items

Use this endpoint to edit an item in your catalog.

prerequisites

Prerequisites

To use this endpoint, you’ll need an API key with the catalogs.update_item permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.
item_idRequiredStringThe ID of the catalog item.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
itemsRequiredArrayAn 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.

example-request

Example request

curl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY' --data-raw '{
"items": [
  {
    "Name": "Restaurant",
    "Loyalty_Program": false,
    "Open_Time": "2021-09-03T09:03:19.967+00:00"
  }
]
}'

response

Response

There are three status code responses for this endpoint: 200, 400, and 404.

example-success-response

Example success response

The status code 200 could return the following response body.

{
"message": "success"
}

example-error-response

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

{
"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

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps.

ErrorTroubleshooting
arbitrary-errorAn arbitrary error occurred. Please try again or contact Support.
catalog-not-foundCheck that the catalog name is valid.
filtered-set-field-too-longThe field value is being used in a filtered set that exceeds the character limit for an item.
id-in-bodyAn item ID already exists in the catalog.
ids-too-largeCharacter limit for each item ID is 250 characters.
invalid-idsSupported characters for item ID names are letters, numbers, hyphens, and underscores.
invalid-fieldsConfirm that the fields in the request exist in the catalog.
invalid-keys-in-value-objectItem object keys can't include . or $.
item-not-foundCheck that the item is in the catalog.
item-array-invaliditems must be an array of objects.
items-too-largeCharacter limit for each item is 5,000 characters.
request-includes-too-many-itemsYou can only edit one catalog item per request.
too-deep-nesting-in-value-objectItem objects can't have more than 50 levels of nesting.
unable-to-coerce-valueItem types can't be converted.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • item_id (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

catalogs_catalog_name_items_item_id_post(connection, catalog_name, item_id, opts \\ [])

@spec catalogs_catalog_name_items_item_id_post(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

create-catalog-item

Create Catalog Item

Use this endpoint to create an item in your catalog.

prerequisites

Prerequisites

To use this endpoint, you’ll need an API key with the catalogs.create_item permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.
item_idRequiredStringThe ID of the catalog item.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
itemsRequiredArrayAn array that contains item objects. The item objects should contain all of the fields in the catalog except for the id field. Only one item object is allowed per request.

example-request

Example Request

curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY' --data-raw '{
"items": [
  {
    "Name": "Restaurant1",
    "City": "New York",
    "Cuisine": "American",
    "Rating": 5,
    "Loyalty_Program": true,
    "Created_At": "2022-11-01T09:03:19.967+00:00"
  }
]
}'

response

Response

There are three status code responses for this endpoint: 201, 400, and 404.

example-success-response

Example success response

The status code 201 could return the following response body.

{
"message": "success"
}

example-error-response

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

{
"errors": [
  {
    "id": "fields-do-not-match",
    "message": "Fields do not match with fields on the catalog",
    "parameters": [
      "id"
    ],
    "parameter_values": [
      "restaurant2"
    ]
  }
],
"message": "Invalid Request"
}

troubleshooting

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps.

ErrorTroubleshooting
already-reached-catalog-item-limitMaximum number of catalogs reached. Contact your Braze account manager for more information.
already-reached-company-item-limitMaximum number of catalog items reached. Contact your Braze account manager for more information.
arbitrary-errorAn arbitrary error occurred. Please try again or contact Support.
catalog-not-foundCheck that the catalog name is valid.
filtered-set-field-too-longThe field value is being used in a filtered set that exceeds the character limit for an item.
id-in-bodyRemove any item IDs in the request body.
ids-too-largeCharacter limit for each item ID is 250 characters.
invalid-idsSupported characters for item ID names are letters, numbers, hyphens, and underscores.
invalid-fieldsConfirm that the fields in the request exist in the catalog.
invalid-keys-in-value-objectItem object keys can't include . or $.
item-already-existsThe item already exists in the catalog.
item-array-invaliditems must be an array of objects.
items-too-largeCharacter limit for each item is 5,000 characters.
request-includes-too-many-itemsYou can only create one catalog item per request.
too-deep-nesting-in-value-objectItem objects can't have more than 50 levels of nesting.
unable-to-coerce-valueItem types can't be converted.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • item_id (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

catalogs_catalog_name_items_item_id_put(connection, catalog_name, item_id, opts \\ [])

@spec catalogs_catalog_name_items_item_id_put(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

update-catalog-item

Update Catalog Item

Use this endpoint to update an item in your catalog.

If the item_id isn't found, this endpoint will create the item. This endpoint is synchronous.

prerequisites

Prerequisites

To use this endpoint, you'll need an API key with the catalogs.replace_item permission.

rate-limit

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.

path-parameters

Path parameters

ParameterRequiredData TypeDescription
catalog_nameRequiredStringName of the catalog.
item_idRequiredStringThe ID of the catalog item.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
itemsRequiredArrayAn 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.

example-request

Example request

curl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' --header 'Content-Type: application/json' --header 'Authorization: Bearer YOUR-REST-API-KEY' --data-raw '{
"items": [
  {
    "Name": "Restaurant",
    "Loyalty_Program": false,
    "Location": {
      "Latitude": 33.6112,
      "Longitude": -117.8711
    },
    "Open_Time": "2021-09-03T09:03:19.967+00:00"
  }
]
}'

response

Response

There are three status code responses for this endpoint: 200, 400, and 404.

example-success-response

Example success response

The status code 200 could return the following response body.

{
"message": "success"
}

example-error-response

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

{
"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

Troubleshooting

The following table lists possible returned errors and their associated troubleshooting steps.

ErrorTroubleshooting
already_reached_catalog_item_limitMaximum number of catalogs reached. Contact your Braze account manager for more information.
already_reached_company_item_limitMaximum number of items reached. Contact your Braze account manager for more information.
arbitrary_errorAn arbitrary error occurred. Please try again or contact Support.
catalog_not_foundCheck that the catalog name is valid.
filtered-set-field-too-longThe field value is being used in a filtered set that exceeds the character limit for an item.
id_in_bodyRemove any item IDs in the request body.
ids_too_largeCharacter limit for each item ID is 250 characters.
invalid_idsSupported characters for item ID names are letters, numbers, hyphens, and underscores.
invalid_fieldsConfirm that the fields in the request exist in the catalog.
invalid_keys_in_value_objectItem object keys can't include . or $.
item_already_existsThe item already exists in the catalog.
item_array_invaliditems must be an array of objects.
items_too_largeItem values can't exceed 5,000 characters.
request_includes_too_many_itemsYour request has too many items. The item limit per request is 50.
too_deep_nesting_in_value_objectItem objects can't have more than 50 levels of nesting.
unable_to_coerce_valueItem types can't be converted.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • catalog_name (String.t):
  • item_id (String.t):
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure