Brands

Brand limits

GET read_products

Fetch Brand limits and per-field constraints.

Returns the per-field maximum lengths and request caps that apply to Brand endpoints. Useful for clients to validate inputs before sending them and to size UIs.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

curl 'https://api-store.tringify.com/api/2025-01/brands/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/brands/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "count": 2,
    "fields": {
      "description": {
        "max_length": 5000
      },
      "name": {
        "max_length": 100
      },
      "seo_description": {
        "max_length": 160
      },
      "seo_title": {
        "max_length": 70
      },
      "slug": {
        "max_length": 100
      }
    },
    "max_per_store": 10,
    "request_caps": {
      "bulk_create_max_count": 50,
      "bulk_delete_max_count": 500,
      "list_max_limit": 100,
      "max_per_store": 10,
      "search_max_length": 200,
      "search_max_limit": 50,
      "slug_retry_max": 100
    },
    "resource_type": "brand",
    "usage": "Brands 2 of 10"
  },
  "success": true
}

List brands

GET read_products

List brands for the store.

Returns brands and their product counts. Each page holds at most 100 brands, and every row carries the full Brand fields, description included. Search matches names and slugs; matches are ordered by relevance (exact name, name prefix, exact slug, slug prefix, then other matches), then by the sort field. Use the returned cursors unchanged, and start without a cursor when search or sorting changes. Fetch /brands/limits for page-size and search limits; supported sort fields are listed below. storefront_url uses the store's primary domain; storefront_path is the base path without a domain. Shopper-facing URLs may use translated slugs and locale/country prefixes.

Query parameters

Name	Type	Description
`cursor`	`string`	Opaque cursor returned by the preceding Brand list response.
`limit`	`integer`	Page size, 1-100 (default 50). Larger values return VALIDATION_LIST_INVALID_LIMIT. Example: `20`
`search`	`string`	Search query. Example: `acme`
`sort_by`	`string`	Sort field from the Brand list contract. Allowed values `nameproduct_countcreated_atupdated_at` Example: `name`
`sort_direction`	`string`	Sort direction from the Brand list contract. Allowed values `ascdesc` Example: `asc`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 INVALID_INPUT
Cursor is malformed or does not match the current Brand list state.
400 VALIDATION_LIST_INVALID_LIMIT
Limit is outside the Brand contract range.
400 VALIDATION_LIST_INVALID_SORT_BY
Sort_by is not a sortable Brand column.
400 VALIDATION_LIST_INVALID_SORT_DIRECTION
Sort_direction is not supported.
400 VALIDATION_SEARCH_TOO_LONG
Search exceeds the Brand contract maximum length.
400 LIST_RESPONSE_TOO_LARGE
The page would be larger than the 512 KiB reply budget (long descriptions or many options). Request it again with a lower limit; error.params.fit estimates how many rows fit.

curl 'https://api-store.tringify.com/api/2025-01/brands?limit=20&search=acme&sort_by=name&sort_direction=asc' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands?limit=20&search=acme&sort_by=name&sort_direction=asc", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/brands?limit=20&search=acme&sort_by=name&sort_direction=asc",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "brands": [
      {
        "created_at": "2026-06-09T12:00:00+05:30",
        "description": "Acme makes durable outdoor gear.",
        "id": 7,
        "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
        "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "name": "Acme",
        "product_count": 12,
        "seo_description": "Shop Acme outdoor gear.",
        "seo_title": "Acme Outdoor Gear",
        "slug": "acme",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "storefront_path": "/brand/acme",
        "storefront_url": "https://store.example.com/brand/acme",
        "template_handle": "default_brand",
        "translations_updated_at": "2026-06-09T12:00:00+05:30",
        "updated_at": "2026-06-09T12:00:00+05:30"
      }
    ],
    "has_next": false,
    "has_previous": false,
    "limit": 20,
    "next_cursor": null,
    "previous_cursor": null,
    "sort_by": "name",
    "sort_direction": "asc",
    "store_total": 1,
    "total": 1
  },
  "success": true
}

Search brands

GET read_products

Search brands for picker-style suggestions.

Returns lightweight brand suggestions by query. This endpoint is intended for pickers and simple selection UIs.

Query parameters

Name	Type	Description
`q`	`string`	Search query. Example: `acme`
`limit`	`integer`	Suggestion count, 1-50 (default 10). Example: `10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 VALIDATION_LIST_INVALID_LIMIT
Limit is outside the Brand search range.
400 VALIDATION_SEARCH_TOO_LONG
Q exceeds the Brand contract maximum length.

curl 'https://api-store.tringify.com/api/2025-01/brands/search?limit=10&q=acme' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/search?limit=10&q=acme", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/brands/search?limit=10&q=acme",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "brands": [
      {
        "id": 7,
        "name": "Acme",
        "slug": "acme"
      }
    ]
  },
  "success": true
}

Get a brand

GET read_products

Fetch one brand by id.

Returns the brand if it belongs to the token's store. storefront_url uses the store's primary domain; storefront_path is the base path without a domain. Shopper-facing URLs may use translated slugs and locale/country prefixes.

Path parameters

Name	Type	Description
`id` required	`integer`	Brand id. Example: `7`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_BRAND_ID
Brand id is invalid.
404 BRAND_NOT_FOUND
Brand does not exist in this store.

curl 'https://api-store.tringify.com/api/2025-01/brands/7' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/7", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/brands/7",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 12,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/brand/acme",
    "storefront_url": "https://store.example.com/brand/acme",
    "template_handle": "default_brand",
    "translations_updated_at": "2026-06-09T12:00:00+05:30",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "success": true
}

List brand metafields

GET read_products

List brand metafield values visible to the token.

Returns paginated metafield values the token can read. total counts only visible values. Identify each value by namespace and key.

Path parameters

Name	Type	Description
`id` required	`integer`	Brand id. Example: `7`

Query parameters

Name	Type	Description
`page`	`integer`	Page number (default 1).
`limit`	`integer`	Page size; capped by the metafield list limit.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_BRAND_ID
Brand id is not a positive integer.
400 VALIDATION_LIST_INVALID_PAGE
Page must be at least 1.
400 VALIDATION_LIST_INVALID_LIMIT
Limit is outside the supported range.
404 NOT_FOUND
Brand does not exist in this store.

curl 'https://api-store.tringify.com/api/2025-01/brands/7/metafields' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/7/metafields", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/brands/7/metafields",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "limit": 50,
    "metafields": [
      {
        "key": "material",
        "namespace": "specs",
        "type": "string",
        "value": "Organic cotton"
      }
    ],
    "page": 1,
    "total": 1,
    "total_pages": 1
  },
  "success": true
}

Set brand metafields

PUT write_products

Create, update, or delete brand metafield values.

Send namespace-and-key entries. A string value creates or replaces a value; null or an empty string deletes it. Only definitions writable by this token can be changed.

Path parameters

Name	Type	Description
`id` required	`integer`	Brand id. Example: `7`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`metafields` required	`array<object>`	Entries shaped as `{namespace, key, value}`. `value` is required in every entry; send `null` or an empty string to delete the stored value. Example: `[{"namespace":"details","key":"origin","value":"Seoul"}]`

Errors

400 STORE_API_INVALID_BRAND_ID
Brand id is not a positive integer.
400 STORE_API_INVALID_REQUEST_BODY
Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 METAFIELD_NO_WRITES
At least one metafield entry is required.
400 METAFIELD_DUPLICATE_WRITE
The request contains the same namespace and key more than once.
400 PRODUCT_METAFIELD_DEF_NOT_FOUND
The namespace and key do not identify a definition visible to the token. For an app token only its own definitions count: merchant-owned and other apps' definitions return this code.
403 METAFIELD_WRITE_MERCHANT_READ_ONLY
This app-owned definition is not writable by the token.
404 NOT_FOUND
Brand does not exist in this store. A file reference names a file that does not exist in this store.
400 METAFIELD_VALUE_TOO_LONG
The value exceeds its size limit: the definition's max_value_length, or the platform value size limit for the type.
400 METAFIELD_VALUE_STRING_TOO_LONG
A string value exceeds the definition's max_value_length or the platform string limit.
400 METAFIELD_VALUE_TOO_SHORT
A string value is shorter than the definition's min_length rule.
400 METAFIELD_VALUE_PATTERN_MISMATCH
A string value does not match the definition's pattern rule.
400 METAFIELD_VALUE_INTEGER_INVALID
An integer value is not a whole number in the 64-bit range.
400 METAFIELD_VALUE_INTEGER_TOO_LONG
An integer value has more digits than the definition or the platform integer limit allows.
400 METAFIELD_VALUE_DECIMAL_INVALID
A decimal value is not a finite decimal number.
400 METAFIELD_VALUE_DECIMAL_TOO_LONG
A decimal value, written out in full, is longer than the definition or the platform decimal limit allows.
400 METAFIELD_VALUE_BELOW_MIN
An integer or decimal value is below the definition's min rule.
400 METAFIELD_VALUE_ABOVE_MAX
An integer or decimal value is above the definition's max rule.
400 METAFIELD_VALUE_BOOLEAN_INVALID
A boolean value is not true or false.
400 METAFIELD_VALUE_DATE_INVALID
A date value is not a calendar date in YYYY-MM-DD form.
400 METAFIELD_VALUE_DATETIME_INVALID
A datetime value is not YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:ss or an RFC 3339 timestamp.
400 METAFIELD_VALUE_JSON_INVALID
A json value is not valid JSON.
400 METAFIELD_VALUE_JSON_UNSAFE_LINK
A json value contains a link whose scheme is not http, https, mailto or tel.
400 METAFIELD_VALUE_URL_INVALID
A url value, or an item of a list.url value, is not an absolute URL with a host.
400 METAFIELD_VALUE_URL_SCHEME
A url value, or an item of a list.url value, does not use http or https.
400 METAFIELD_VALUE_URL_TOO_LONG
A url value, or an item of a list.url value, exceeds the definition's max_value_length or the platform URL limit.
400 METAFIELD_VALUE_NOT_IN_CHOICES
A single_select value is not one of the definition's choice keys.
400 METAFIELD_LIST_CHOICE_INVALID
An item of a list.single_select value is not one of the definition's choice keys; the message names the item.
400 METAFIELD_LIST_STRINGS_INVALID
A list.string or list.single_select value is not a JSON array of strings.
400 METAFIELD_LIST_URLS_INVALID
A list.url value is not a JSON array of strings.
400 METAFIELD_LIST_FILES_INVALID
A list.file_reference value is not a JSON array of strings.
400 METAFIELD_LIST_IDS_INVALID
A list.product_reference or list.variant_reference value is not a JSON array of integers.
400 METAFIELD_LIST_EMPTY
A list value other than list.string is an empty array. Send null or an empty string to remove the value instead.
400 METAFIELD_LIST_TOO_MANY
A list value has more items than the definition's max_list_items or the platform list limit for the type.
400 METAFIELD_LIST_ITEM_EMPTY
An item of a list.string value is empty or only whitespace; the message names the item.
400 METAFIELD_LIST_ITEM_TOO_LONG
An item of a list.string value exceeds the definition's max_value_length or the platform string limit; the message names the item.
400 METAFIELD_VALUE_FILE_UUID_INVALID
A file_reference value, or an item of a list.file_reference value, is not a file UUID.
400 METAFIELD_VALUE_ID_INVALID
A product_reference or variant_reference value is not an integer ID.
400 METAFIELD_VALUE_ID_POSITIVE
A product_reference or variant_reference value is not a positive integer.
400 METAFIELD_VALUE_ID_TOO_LONG
A product_reference or variant_reference value exceeds the platform reference ID limit.
400 METAFIELD_LIST_ITEMS_POSITIVE
An item of a list.product_reference or list.variant_reference value is not a positive integer.
400 METAFIELD_REFERENCE_PRODUCT_MISSING
A product reference names a product that does not exist in this store.
400 METAFIELD_REFERENCE_VARIANT_MISSING
A variant reference names a variant that does not exist in this store.
400 INVALID_INPUT
A file reference names a file that is not an uploaded file.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/brands/7/metafields' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "metafields": [
    {
      "key": "origin",
      "namespace": "details",
      "value": "Seoul"
    }
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/7/metafields", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "metafields": [
      {
        "key": "origin",
        "namespace": "details",
        "value": "Seoul"
      }
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/brands/7/metafields",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "metafields": [{
            "key": "origin",
            "namespace": "details",
            "value": "Seoul",
        }],
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "limit": 50,
    "metafields": [
      {
        "key": "material",
        "namespace": "specs",
        "type": "string",
        "value": "Organic cotton"
      }
    ],
    "page": 1,
    "total": 1,
    "total_pages": 1
  },
  "success": true
}

Create a brand

POST write_products

Create a brand.

Create with name; omit slug to generate it. Omitted or empty template_handle uses default_brand. A non-empty image_id must reference an uploaded image in this store and also requires read_files; video, documents, 3D models, and site assets are rejected. storefront_url uses the store's primary domain; storefront_path is the base path without a domain. Shopper-facing URLs may use translated slugs and locale/country prefixes.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.
`Idempotency-Key`	`string`	Optional key, up to 255 characters, that makes this create safe to retry. Repeating the request with the same key and body within 24 hours returns the original response instead of creating again; the same key with a different body returns `CATALOG_REQUEST_KEY_CONFLICT`.

Body parameters

Name	Type	Description
`name` required	`string`	Brand name. Example: `Acme`
`slug`	`string`	Optional slug. Omit to generate from name. Example: `acme`
`description`	`string`	Optional plain-text description. Omit or send an empty string for no description. Example: `Acme makes durable outdoor gear.`
`seo_title`	`string`	Optional SEO title. Omit or send an empty string to let the storefront fall back to the Brand name. Example: `Acme Outdoor Gear`
`seo_description`	`string`	Optional SEO description. Omit or send an empty string to let the storefront fall back to the Brand description. Example: `Shop Acme outdoor gear.`
`image_id`	`string`	Optional Media-library upload image UUID. Video, document, 3D-model, and site-asset ids are invalid. Non-empty values require `read_files` access to the referenced file. Example: `8f2a1c2b-9d4e-4a56-b789-0123456789ab`
`template_handle`	`string`	Brand template assignment. Omit this field, send an empty string, or send `default_brand` to use the default Brand template. Otherwise, send a Brand template handle available in the store's active theme. Example: `default_brand`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 STORE_API_CREATE_REDIRECT_UNSUPPORTED
Create_redirect is only supported when updating a brand.
400 BRAND_NAME_REQUIRED
Name is required.
400 BRAND_NAME_INVALID_CHARS
Name contains unsupported control characters.
400 BRAND_NAME_TOO_LONG
Name exceeds the maximum length.
400 BRAND_DESCRIPTION_INVALID_CHARS
Description contains unsupported control characters.
400 BRAND_DESCRIPTION_TOO_LONG
Description exceeds the maximum length.
400 BRAND_SEO_TITLE_INVALID_CHARS
SEO title contains unsupported control characters.
400 BRAND_SEO_TITLE_TOO_LONG
SEO title exceeds the maximum length.
400 BRAND_SEO_DESCRIPTION_INVALID_CHARS
SEO description contains unsupported control characters.
400 BRAND_SEO_DESCRIPTION_TOO_LONG
SEO description exceeds the maximum length.
400 BRAND_SLUG_INVALID_FORMAT
Slug is not valid for Brand URLs.
400 BRAND_SLUG_TOO_LONG
Slug exceeds the maximum length.
400 TEMPLATE_HANDLE_INVALID
Template handle is not valid for Brand templates.
400 TEMPLATE_HANDLE_NOT_FOUND
Template handle is not available for this store.
400 INVALID_INPUT
image_id is invalid or does not refer to an uploaded image in this store.
403 STORE_API_SCOPE_REQUIRED
A non-empty image_id requires read_files scope in addition to write_products.
404 NOT_FOUND
The supplied image does not exist in this store.
409 BRAND_DUPLICATE
Name or slug already belongs to another brand in this store, in any language. error.details.existing_id is that brand's id, so a retried create can fetch it instead of creating it again.
409 BRAND_DELETE_IN_PROGRESS
A brand that is still being deleted holds the name or slug. Retry once the delete finishes.
400 BRAND_SLUG_GENERATION_FAILED
A slug could not be generated from the supplied name.
400 BRAND_UNIQUE_SLUG_GENERATION_FAILED
A unique generated slug could not be found; supply a slug explicitly.
400 BRAND_PLAN_LIMIT_REACHED
The store has as many brands as its plan allows; the message states the maximum. Fetch /brands/limits for the store's current cap and usage.
503 CATALOG_NAMESPACE_BUSY
Another write is claiming the same names or slugs (for example a large CSV import or a translation save). Nothing was changed; retry after a short delay.
400 CATALOG_REQUEST_KEY_TOO_LONG
Idempotency-Key is longer than 255 characters.
403 PLAN_UNKNOWN
The store has no active plan, so nothing can be created until one is chosen.
409 CATALOG_REQUEST_KEY_CONFLICT
Idempotency-Key was already used with a different request body.

curl -X POST 'https://api-store.tringify.com/api/2025-01/brands' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Acme makes durable outdoor gear.",
  "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
  "name": "Acme",
  "seo_description": "Shop Acme outdoor gear.",
  "seo_title": "Acme Outdoor Gear",
  "slug": "acme",
  "template_handle": "default_brand"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "description": "Acme makes durable outdoor gear.",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "template_handle": "default_brand"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/brands",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "description": "Acme makes durable outdoor gear.",
        "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "name": "Acme",
        "seo_description": "Shop Acme outdoor gear.",
        "seo_title": "Acme Outdoor Gear",
        "slug": "acme",
        "template_handle": "default_brand",
    },
)
data = res.json()

Response

201

Sample response

{
  "code": "BRAND_CREATED",
  "data": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 0,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/brand/acme",
    "storefront_url": "https://store.example.com/brand/acme",
    "template_handle": "default_brand",
    "translations_updated_at": null,
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "message": "Brand 'Acme' created.",
  "success": true
}

Bulk create brands

POST write_products

Create multiple brands by name.

Creates brands from names and generates their slugs. Existing names appear in skipped; invalid rows are reported without blocking valid ones. storefront_url uses the store's primary domain; storefront_path is the base path without a domain. Shopper-facing URLs may use translated slugs and locale/country prefixes.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.
`Idempotency-Key`	`string`	Optional key, up to 255 characters, that makes this create safe to retry. Repeating the request with the same key and body within 24 hours returns the original response instead of creating again; the same key with a different body returns `CATALOG_REQUEST_KEY_CONFLICT`.

Body parameters

Name	Type	Description
`names` required	`array<string>`	Brand names to create. Example: `["Acme", "Northwind"]`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 BRAND_BULK_NO_NAMES
No names were provided.
400 BRAND_BULK_CREATE_TOO_MANY
Batch exceeds the Brand bulk create cap.
409 BRAND_BULK_DUPLICATE
One of the names in the batch was just created by another request.
503 CATALOG_NAMESPACE_BUSY
Another write is claiming the same names or slugs (for example a large CSV import or a translation save). Nothing was changed; retry after a short delay.
400 CATALOG_REQUEST_KEY_TOO_LONG
Idempotency-Key is longer than 255 characters.
403 PLAN_UNKNOWN
The store has no active plan, so nothing can be created until one is chosen.
409 CATALOG_REQUEST_KEY_CONFLICT
Idempotency-Key was already used with a different request body.

curl -X POST 'https://api-store.tringify.com/api/2025-01/brands/bulk-create' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "Acme",
    "Northwind"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/bulk-create", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "names": [
      "Acme",
      "Northwind"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/brands/bulk-create",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "names": ["Acme", "Northwind"],
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "created": [
      {
        "created_at": "2026-06-09T12:00:00+05:30",
        "description": "",
        "id": 7,
        "image_cdn_url": "",
        "image_id": null,
        "image_url": "",
        "name": "Acme",
        "product_count": 0,
        "seo_description": "",
        "seo_title": "",
        "slug": "acme",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "storefront_path": "/brand/acme",
        "storefront_url": "https://store.example.com/brand/acme",
        "template_handle": "default_brand",
        "translations_updated_at": null,
        "updated_at": "2026-06-09T12:00:00+05:30"
      }
    ],
    "errors": [],
    "row_errors": [],
    "skipped": [
      "Existing Brand"
    ]
  },
  "success": true
}

Update a brand

PUT write_products

Update a brand.

Changes only supplied fields. Empty optional text or image_id clears that field; clear a text field's translations first. A non-empty image_id must reference an uploaded image in this store and also requires read_files; video, documents, 3D models, and site assets are rejected. Omit template_handle to keep it, or send default_brand to reset it; an empty value is invalid. A slug change creates a redirect unless create_redirect is false. storefront_url uses the store's primary domain; storefront_path is the base path without a domain. Shopper-facing URLs may use translated slugs and locale/country prefixes.

Path parameters

Name	Type	Description
`id` required	`integer`	Brand id. Example: `7`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name`	`string`	New Brand name. Omit to leave it unchanged; an empty value is invalid. Example: `Acme`
`slug`	`string`	New slug. Omit to leave the current slug unchanged; an empty value is invalid. Example: `acme`
`description`	`string`	New plain-text description. Omit to leave it unchanged; send an empty string to clear it. Example: `Acme makes durable outdoor gear.`
`seo_title`	`string`	New SEO title. Omit to leave it unchanged; send an empty string to clear it and restore the storefront Brand-name fallback. Example: `Acme Outdoor Gear`
`seo_description`	`string`	New SEO description. Omit to leave it unchanged; send an empty string to clear it and restore the storefront Brand-description fallback. Example: `Shop Acme outdoor gear.`
`image_id`	`string`	New Media-library upload image UUID. Omit to leave the image unchanged; send an empty string to clear it. A non-empty value requires `read_files` access and must reference an image upload in this store. Example: `8f2a1c2b-9d4e-4a56-b789-0123456789ab`
`template_handle`	`string`	New Brand template assignment. Omit to leave it unchanged, send `default_brand` to use the default Brand template, or send another Brand template handle available in the store's active theme. An empty string is invalid. Example: `default_brand`
`create_redirect`	`boolean`	When slug changes, create a redirect from the previous slug. Example: `true`

Errors

400 STORE_API_INVALID_BRAND_ID
Brand id is invalid.
400 STORE_API_INVALID_REQUEST_BODY
Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 BRAND_NAME_REQUIRED
Name is required.
400 BRAND_NAME_INVALID_CHARS
Name contains unsupported control characters.
400 BRAND_NAME_TOO_LONG
Name exceeds the maximum length.
400 BRAND_DESCRIPTION_INVALID_CHARS
Description contains unsupported control characters.
400 BRAND_DESCRIPTION_TOO_LONG
Description exceeds the maximum length.
400 BRAND_SEO_TITLE_INVALID_CHARS
SEO title contains unsupported control characters.
400 BRAND_SEO_TITLE_TOO_LONG
SEO title exceeds the maximum length.
400 BRAND_SEO_DESCRIPTION_INVALID_CHARS
SEO description contains unsupported control characters.
400 BRAND_SEO_DESCRIPTION_TOO_LONG
SEO description exceeds the maximum length.
400 BRAND_SLUG_INVALID_FORMAT
Slug is not valid for Brand URLs.
400 BRAND_SLUG_TOO_LONG
Slug exceeds the maximum length.
400 TEMPLATE_HANDLE_INVALID
Template handle is not valid for Brand templates.
400 TEMPLATE_HANDLE_NOT_FOUND
Template handle is not available for this store.
400 INVALID_INPUT
image_id is invalid or does not refer to an uploaded image in this store.
403 STORE_API_SCOPE_REQUIRED
A non-empty image_id requires read_files scope in addition to write_products.
404 NOT_FOUND
The supplied image does not exist in this store.
409 BRAND_DUPLICATE
Name or slug already belongs to another brand in this store, in any language. error.details.existing_id is that brand's id, so a retried create can fetch it instead of creating it again.
409 BRAND_DELETE_IN_PROGRESS
A brand that is still being deleted holds the name or slug. Retry once the delete finishes.
503 CATALOG_NAMESPACE_BUSY
Another write is claiming the same names or slugs (for example a large CSV import or a translation save). Nothing was changed; retry after a short delay.
404 BRAND_NOT_FOUND
Brand does not exist in this store.
409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS
Clear a field's translations before clearing its source value.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/brands/7' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "create_redirect": true,
  "description": "Acme makes durable outdoor gear.",
  "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
  "name": "Acme",
  "seo_description": "Shop Acme outdoor gear.",
  "seo_title": "Acme Outdoor Gear",
  "slug": "acme",
  "template_handle": "default_brand"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/7", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "create_redirect": true,
    "description": "Acme makes durable outdoor gear.",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "template_handle": "default_brand"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/brands/7",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "create_redirect": True,
        "description": "Acme makes durable outdoor gear.",
        "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "name": "Acme",
        "seo_description": "Shop Acme outdoor gear.",
        "seo_title": "Acme Outdoor Gear",
        "slug": "acme",
        "template_handle": "default_brand",
    },
)
data = res.json()

Response

200

Sample response

{
  "code": "BRAND_UPDATED",
  "data": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 12,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/brand/acme",
    "storefront_url": "https://store.example.com/brand/acme",
    "template_handle": "default_brand",
    "translations_updated_at": "2026-06-09T12:00:00+05:30",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "message": "Brand 'Acme' updated.",
  "success": true
}

Delete a brand

DELETE write_products

Delete a brand.

Deletes the brand, its translations, and its metafield values. If products, collection rules, or menu links use it, the first request returns CONFIRMATION_REQUIRED; repeat with confirmed: true and the returned confirmation_token. The brand, product assignments, and collection rules change atomically. Deletion emits one brands/translations/delete per translated locale and a brands/delete event. Menu links may update shortly after the response.

Path parameters

Name	Type	Description
`id` required	`integer`	Brand id. Example: `7`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

400 STORE_API_INVALID_BRAND_ID
Brand id is invalid.
400 STORE_API_INVALID_REQUEST_BODY
A non-empty request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 BRAND_CONFIRMATION_INVALID
Confirmation token is missing, expired, or mismatched.
404 BRAND_NOT_FOUND
Brand does not exist in this store.
409 CONFIRMATION_REQUIRED
Delete requires confirmation because dependent records will be changed.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/brands/7' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/7", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/brands/7",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "deleted": true,
    "id": 7,
    "name": "Acme"
  },
  "success": true
}

Bulk delete brands

POST write_products

Delete multiple brands.

Send brand IDs in brand_ids. If deletion affects products, collection rules, or menu links, repeat the request with confirmed: true and the returned confirmation_token. The response lists removed IDs in deleted and missing or changed IDs in failed. IDs listed in deleted are removed atomically. Menu links may update shortly after the response.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`brand_ids` required	`array<integer>`	Store-scoped integer brand ids to delete. Example: `[7, 11]`
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
400 BRAND_BULK_NO_IDS
No brand ids were provided.
400 BRAND_BULK_DELETE_TOO_MANY
Batch exceeds the Brand bulk delete cap.
409 BRAND_BULK_RACED
Dependencies changed while the bulk delete was running; retry with fresh state.
400 BRAND_CONFIRMATION_INVALID
Confirmation token is missing, expired, or mismatched.
404 BRAND_NOT_FOUND
Brand does not exist in this store.
409 CONFIRMATION_REQUIRED
Delete requires confirmation because dependent records will be changed.

curl -X POST 'https://api-store.tringify.com/api/2025-01/brands/bulk-delete' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "brand_ids": [
    7,
    11
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/brands/bulk-delete", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "brand_ids": [
      7,
      11
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/brands/bulk-delete",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "brand_ids": [7, 11],
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "deleted": [
      7
    ],
    "failed": [
      {
        "id": 11,
        "reason": "Brand not found."
      }
    ]
  },
  "success": true
}

Field	Create	Update	Required	Translatable
`id`	No	No		No
`store_id`	No	No		No
`name`	Yes	Yes	create	Yes
`slug`	Yes	Yes		Yes
`description`	Yes	Yes		Yes
`seo_title`	Yes	Yes		Yes
`seo_description`	Yes	Yes		Yes
`image_id`	Yes	Yes		No
`image_url`	No	No		No
`image_cdn_url`	No	No		No
`template_handle`	Yes	Yes		No
`create_redirect`	No	Yes		No
`product_count`	No	No		No
`created_at`	No	No		No
`updated_at`	No	No		No
`translations_updated_at`	No	No		No
`storefront_url`	No	No	No	No
`storefront_path`	No	No	No	No

Brand created

EVENT brands/create App scope: read_products Staff permission: products:write

Fired when a brand is created.

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present The stable Brand id.
`brand.name`	`string`	Selectable in the Payload builder The merchant-facing Brand name.
`brand.slug`	`string`	Selectable in the Payload builder The Brand's URL-safe identifier.
`brand.description`	`string`	Selectable in the Payload builder The Brand description in the store's default locale.
`brand.seo_title`	`string`	Selectable in the Payload builder The Brand page's SEO title in the store's default locale.
`brand.seo_description`	`string`	Selectable in the Payload builder The Brand page's SEO description in the store's default locale.
`brand.image_id`	`string`	Selectable in the Payload builder The assigned Media-library image id, or null when no image is assigned.
`brand.image_url`	`string`	Selectable in the Payload builder The original URL recorded for the assigned image, or an empty string.
`brand.image_cdn_url`	`string`	Selectable in the Payload builder The delivery URL for the assigned image, or an empty string.
`brand.product_count`	`integer`	Selectable in the Payload builder The number of products currently assigned to the Brand.
`brand.template_handle`	`string`	Selectable in the Payload builder The storefront template handle assigned to the Brand.
`brand.created_at`	`string`	Selectable in the Payload builder When the Brand was created.
`brand.updated_at`	`string`	Selectable in the Payload builder When the Brand last changed.
`brand.translations_updated_at`	`string`	Selectable in the Payload builder When any Brand translation last changed, or null when none exist.

Payload shape

Sample payload

{
  "brand": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 0,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "template_handle": "default_brand",
    "translations_updated_at": null,
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Brand updated

EVENT brands/update App scope: read_products Staff permission: products:write

Fired when a brand changes. change_type is source for Brand field edits and assignments when product assignments change its product count. Source changes include previous and changed_fields; assignment changes report product_count in changed_fields. During a CSV product import, assignments changes are sent once per import chunk for each brand whose products changed, carrying the counts after the chunk. A rename is announced by this event alone (changed_fields includes name): the brand's products do not each get products/update (channel apps still get product_publications/update for products on their channel), so refresh any brand name you cache on products from it.

Possible `changed_fields` values

The changed_fields array names exactly which of these changed in this event — use it to skip processing updates your integration doesn't care about.

description image_id name product_count seo_description seo_title slug template_handle

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present The stable Brand id.
`brand.name`	`string`	Selectable in the Payload builder The merchant-facing Brand name.
`brand.slug`	`string`	Selectable in the Payload builder The Brand's URL-safe identifier.
`brand.description`	`string`	Selectable in the Payload builder The Brand description in the store's default locale.
`brand.seo_title`	`string`	Selectable in the Payload builder The Brand page's SEO title in the store's default locale.
`brand.seo_description`	`string`	Selectable in the Payload builder The Brand page's SEO description in the store's default locale.
`brand.image_id`	`string`	Selectable in the Payload builder The assigned Media-library image id, or null when no image is assigned.
`brand.image_url`	`string`	Selectable in the Payload builder The original URL recorded for the assigned image, or an empty string.
`brand.image_cdn_url`	`string`	Selectable in the Payload builder The delivery URL for the assigned image, or an empty string.
`brand.product_count`	`integer`	Selectable in the Payload builder The number of products currently assigned to the Brand.
`brand.template_handle`	`string`	Selectable in the Payload builder The storefront template handle assigned to the Brand.
`brand.created_at`	`string`	Selectable in the Payload builder When the Brand was created.
`brand.updated_at`	`string`	Selectable in the Payload builder When the Brand last changed.
`brand.translations_updated_at`	`string`	Selectable in the Payload builder When any Brand translation last changed, or null when none exist.
`previous.id`	`integer`	Always present The stable Brand id. This value is from before the update.
`previous.name`	`string`	Selectable in the Payload builder The merchant-facing Brand name. This value is from before the update.
`previous.slug`	`string`	Selectable in the Payload builder The Brand's URL-safe identifier. This value is from before the update.
`previous.description`	`string`	Selectable in the Payload builder The Brand description in the store's default locale. This value is from before the update.
`previous.seo_title`	`string`	Selectable in the Payload builder The Brand page's SEO title in the store's default locale. This value is from before the update.
`previous.seo_description`	`string`	Selectable in the Payload builder The Brand page's SEO description in the store's default locale. This value is from before the update.
`previous.image_id`	`string`	Selectable in the Payload builder The assigned Media-library image id, or null when no image is assigned. This value is from before the update.
`previous.image_url`	`string`	Selectable in the Payload builder The original URL recorded for the assigned image, or an empty string. This value is from before the update.
`previous.image_cdn_url`	`string`	Selectable in the Payload builder The delivery URL for the assigned image, or an empty string. This value is from before the update.
`previous.product_count`	`integer`	Selectable in the Payload builder The number of products currently assigned to the Brand. This value is from before the update.
`previous.template_handle`	`string`	Selectable in the Payload builder The storefront template handle assigned to the Brand. This value is from before the update.
`previous.created_at`	`string`	Selectable in the Payload builder When the Brand was created. This value is from before the update.
`previous.updated_at`	`string`	Selectable in the Payload builder When the Brand last changed. This value is from before the update.
`previous.translations_updated_at`	`string`	Selectable in the Payload builder When any Brand translation last changed, or null when none exist. This value is from before the update.
`changed_fields`	`array`	Always present The Brand fields changed by this event.
`change_type`	`string`	Always present Why brands/update fired: source for Brand field edits or assignments for product assignment-count changes.

Payload shape

Sample payload

{
  "brand": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 12,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "template_handle": "default_brand",
    "translations_updated_at": "2026-06-09T12:00:00+05:30",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "change_type": "source",
  "changed_fields": [
    "name"
  ],
  "previous": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Acme makes durable outdoor gear.",
    "id": 7,
    "image_cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4a56-b789-0123456789ab.jpg",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "image_url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Acme",
    "product_count": 12,
    "seo_description": "Shop Acme outdoor gear.",
    "seo_title": "Acme Outdoor Gear",
    "slug": "acme",
    "template_handle": "default_brand",
    "translations_updated_at": "2026-06-09T12:00:00+05:30",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Brand deleted

EVENT brands/delete App scope: read_products Staff permission: products:write

Fired after a brand is deleted. A brand with translations also produces brands/translations/delete for each translated locale; those events and the deletion are atomic. Removed metafield values have separate delete events.

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present The stable id of the deleted Brand.
`brand.name`	`string`	Selectable in the Payload builder The Brand name at the time it was deleted.
`brand.slug`	`string`	Selectable in the Payload builder The Brand slug at the time it was deleted.

Payload shape

Sample payload

{
  "brand": {
    "id": 7,
    "name": "Acme",
    "slug": "acme"
  }
}

Brand metafield value created

EVENT brand_metafields/create App scope: read_products Staff permission: products:write

Fired when a brand metafield value is created.

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present
`brand.name`	`string`	Selectable in the Payload builder
`brand.slug`	`string`	Selectable in the Payload builder
`metafield.definition.id`	`string`	Selectable in the Payload builder
`metafield.definition.owner_type`	`string`	Selectable in the Payload builder
`metafield.definition.namespace`	`string`	Selectable in the Payload builder
`metafield.definition.key`	`string`	Selectable in the Payload builder
`metafield.definition.name`	`string`	Selectable in the Payload builder
`metafield.definition.description`	`string`	Selectable in the Payload builder
`metafield.definition.type`	`string`	Selectable in the Payload builder
`metafield.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`metafield.definition.max_value_length`	`integer`	Selectable in the Payload builder
`metafield.definition.max_list_items`	`integer`	Selectable in the Payload builder
`metafield.definition.sort_order`	`integer`	Selectable in the Payload builder
`metafield.definition.app_id`	`string`	Selectable in the Payload builder
`metafield.definition.app_access`	`string`	Selectable in the Payload builder
`metafield.definition.merchant_access`	`string`	Selectable in the Payload builder
`metafield.definition.created_at`	`string`	Selectable in the Payload builder
`metafield.definition.updated_at`	`string`	Selectable in the Payload builder
`metafield.definition.usage_count`	`integer`	Selectable in the Payload builder
`metafield.value`	`string`	Selectable in the Payload builder
`metafield.display_value`	`string`	Selectable in the Payload builder
`metafield.display_value_map`	`object`	Selectable in the Payload builder
`metafield.created_at`	`string`	Selectable in the Payload builder
`metafield.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "brand": {
    "id": 7,
    "name": "Acme",
    "slug": "acme"
  },
  "metafield": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": "d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a",
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": "The primary material used by this brand.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "material",
      "max_list_items": null,
      "max_value_length": 100,
      "merchant_access": "read_write",
      "name": "Material",
      "namespace": "app:catalog-sync.details",
      "owner_type": "brand",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 1
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Organic cotton"
  }
}

Brand metafield value updated

EVENT brand_metafields/update App scope: read_products Staff permission: products:write

Fired when a brand metafield value changes.

Possible `changed_fields` values

The changed_fields array names exactly which of these changed in this event — use it to skip processing updates your integration doesn't care about.

value

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present
`brand.name`	`string`	Selectable in the Payload builder
`brand.slug`	`string`	Selectable in the Payload builder
`previous.definition.id`	`string`	Selectable in the Payload builder
`previous.definition.owner_type`	`string`	Selectable in the Payload builder
`previous.definition.namespace`	`string`	Selectable in the Payload builder
`previous.definition.key`	`string`	Selectable in the Payload builder
`previous.definition.name`	`string`	Selectable in the Payload builder
`previous.definition.description`	`string`	Selectable in the Payload builder
`previous.definition.type`	`string`	Selectable in the Payload builder
`previous.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`previous.definition.max_value_length`	`integer`	Selectable in the Payload builder
`previous.definition.max_list_items`	`integer`	Selectable in the Payload builder
`previous.definition.sort_order`	`integer`	Selectable in the Payload builder
`previous.definition.app_id`	`string`	Selectable in the Payload builder
`previous.definition.app_access`	`string`	Selectable in the Payload builder
`previous.definition.merchant_access`	`string`	Selectable in the Payload builder
`previous.definition.created_at`	`string`	Selectable in the Payload builder
`previous.definition.updated_at`	`string`	Selectable in the Payload builder
`previous.definition.usage_count`	`integer`	Selectable in the Payload builder
`previous.value`	`string`	Selectable in the Payload builder
`previous.display_value`	`string`	Selectable in the Payload builder
`previous.display_value_map`	`object`	Selectable in the Payload builder
`previous.created_at`	`string`	Selectable in the Payload builder
`previous.updated_at`	`string`	Selectable in the Payload builder
`current.definition.id`	`string`	Selectable in the Payload builder
`current.definition.owner_type`	`string`	Selectable in the Payload builder
`current.definition.namespace`	`string`	Selectable in the Payload builder
`current.definition.key`	`string`	Selectable in the Payload builder
`current.definition.name`	`string`	Selectable in the Payload builder
`current.definition.description`	`string`	Selectable in the Payload builder
`current.definition.type`	`string`	Selectable in the Payload builder
`current.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`current.definition.max_value_length`	`integer`	Selectable in the Payload builder
`current.definition.max_list_items`	`integer`	Selectable in the Payload builder
`current.definition.sort_order`	`integer`	Selectable in the Payload builder
`current.definition.app_id`	`string`	Selectable in the Payload builder
`current.definition.app_access`	`string`	Selectable in the Payload builder
`current.definition.merchant_access`	`string`	Selectable in the Payload builder
`current.definition.created_at`	`string`	Selectable in the Payload builder
`current.definition.updated_at`	`string`	Selectable in the Payload builder
`current.definition.usage_count`	`integer`	Selectable in the Payload builder
`current.value`	`string`	Selectable in the Payload builder
`current.display_value`	`string`	Selectable in the Payload builder
`current.display_value_map`	`object`	Selectable in the Payload builder
`current.created_at`	`string`	Selectable in the Payload builder
`current.updated_at`	`string`	Selectable in the Payload builder
`changed_fields`	`array`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "brand": {
    "id": 7,
    "name": "Acme",
    "slug": "acme"
  },
  "changed_fields": [
    "value"
  ],
  "current": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": "d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a",
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": "The primary material used by this brand.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "material",
      "max_list_items": null,
      "max_value_length": 100,
      "merchant_access": "read_write",
      "name": "Material",
      "namespace": "app:catalog-sync.details",
      "owner_type": "brand",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 1
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-10T09:30:00+05:30",
    "value": "Recycled cotton"
  },
  "previous": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": "d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a",
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": "The primary material used by this brand.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "material",
      "max_list_items": null,
      "max_value_length": 100,
      "merchant_access": "read_write",
      "name": "Material",
      "namespace": "app:catalog-sync.details",
      "owner_type": "brand",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 1
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Organic cotton"
  }
}

Brand metafield value deleted

EVENT brand_metafields/delete App scope: read_products Staff permission: products:write

Fired when a brand metafield value is deleted.

Payload fields

Field	Type	Description
`brand.id`	`integer`	Always present
`brand.name`	`string`	Selectable in the Payload builder
`brand.slug`	`string`	Selectable in the Payload builder
`metafield.definition.id`	`string`	Selectable in the Payload builder
`metafield.definition.owner_type`	`string`	Selectable in the Payload builder
`metafield.definition.namespace`	`string`	Selectable in the Payload builder
`metafield.definition.key`	`string`	Selectable in the Payload builder
`metafield.definition.name`	`string`	Selectable in the Payload builder
`metafield.definition.description`	`string`	Selectable in the Payload builder
`metafield.definition.type`	`string`	Selectable in the Payload builder
`metafield.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`metafield.definition.max_value_length`	`integer`	Selectable in the Payload builder
`metafield.definition.max_list_items`	`integer`	Selectable in the Payload builder
`metafield.definition.sort_order`	`integer`	Selectable in the Payload builder
`metafield.definition.app_id`	`string`	Selectable in the Payload builder
`metafield.definition.app_access`	`string`	Selectable in the Payload builder
`metafield.definition.merchant_access`	`string`	Selectable in the Payload builder
`metafield.definition.created_at`	`string`	Selectable in the Payload builder
`metafield.definition.updated_at`	`string`	Selectable in the Payload builder
`metafield.definition.usage_count`	`integer`	Selectable in the Payload builder
`metafield.value`	`string`	Selectable in the Payload builder
`metafield.display_value`	`string`	Selectable in the Payload builder
`metafield.display_value_map`	`object`	Selectable in the Payload builder
`metafield.created_at`	`string`	Selectable in the Payload builder
`metafield.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "brand": {
    "id": 7,
    "name": "Acme",
    "slug": "acme"
  },
  "metafield": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": "d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a",
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": "The primary material used by this brand.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "material",
      "max_list_items": null,
      "max_value_length": 100,
      "merchant_access": "read_write",
      "name": "Material",
      "namespace": "app:catalog-sync.details",
      "owner_type": "brand",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 1
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Organic cotton"
  }
}

Product assignments#

Metafield access#

Endpoints#

Headers

Query parameters

Headers

Errors

Query parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Query parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Fields#

Webhook events#

Payload fields

Possible changed_fields values

Payload fields

Payload fields

Payload fields

Possible changed_fields values

Payload fields

Payload fields

Possible `changed_fields` values

Possible `changed_fields` values