Categories

Category limits

GET read_products

Fetch Category limits and per-field constraints.

Returns the per-field maximum lengths, hierarchy depth, and request caps that apply to Category endpoints. Useful for clients to validate inputs before sending them and to size UIs. max_per_store is this store's plan cap, count is how many exist now, and usage is the localized label.

Headers

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

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/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/categories/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "count": 4,
    "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_depth": 5,
      "max_per_store": 10,
      "search_max_length": 200,
      "search_max_limit": 50,
      "slug_retry_max": 100,
      "tree_max_limit": 500
    },
    "resource_type": "category",
    "usage": "Categories 4 of 10"
  },
  "success": true
}

List categories

GET read_products

List categories for the store.

Returns paginated categories. With tree=true and no search or filters, limit paginates root categories; the selected roots and their descendants are then expanded into one nested page. Expansion is deterministic and ancestor-first, with siblings ordered by name and then id, and is capped at request_caps.tree_max_limit total category nodes across the whole root page, including the roots, and at the 512 KiB reply budget. When more nodes exist or the next node would pass the budget, the response returns the prefix that fits and sets truncated: true; later descendants or entire later root subtrees can therefore be absent even when has_next is false. has_next, has_previous, next_cursor, previous_cursor, and total describe root-category pagination only and do not describe omitted descendants. To retrieve every category, use the flat list (tree=false) with cursor pagination; add ancestor_id when a complete flat listing of one category's descendants is needed. Any search or filter also switches the response to the ordinary flat, cursor-paginated list, where truncated is false. A flat page holds at most list_max_limit (100) categories with every field, description included. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Query parameters

Name	Type	Description
`cursor`	`string`	Opaque cursor from a previous `categories.list` response. Omit for the first page; reset when search, filters, tree, or sorting changes. Example: `eyJ2IjoxLCJyIjoiY2F0ZWdvcnkifQ`
`limit`	`integer`	Page size, 1-100 (default 50). Larger values return `CATEGORY_LIST_INVALID_LIMIT`. A page whose rows would exceed the 512 KiB reply budget returns `LIST_RESPONSE_TOO_LARGE`; request it again with a lower limit. Example: `20`
`tree`	`boolean`	When true and no search or filters are active, paginate roots by `limit`, then nest an ancestor-first prefix of their combined subtrees up to `request_caps.tree_max_limit` total nodes. `truncated: true` means later nodes were omitted by that expansion cap; it is independent of root-page `has_next`. Search or filter parameters return the complete flat cursor-paginated result instead. Accepted values: true, false. Example: `false`
`search`	`string`	Search categories by name or slug. Maximum 200 characters. Example: `apparel`
`parent_id`	`string`	`null` for root categories, or a positive parent category id. Example: `null`
`ancestor_id`	`integer`	Filter to descendants of this ancestor category id. Must be a positive integer. Example: `12`
`has_children`	`boolean`	Filter categories by whether they have subcategories. Accepted values: true, false. Example: `true`
`has_images`	`boolean`	Filter categories by whether they have an image. Accepted values: true, false. Example: `true`
`sort_by`	`string`	Sort field. Allowed values: name, product_count, created_at, updated_at. Allowed values `nameproduct_countcreated_atupdated_at` Example: `name`
`sort_direction`	`string`	Sort direction. Allowed values: asc, desc. Allowed values `ascdesc` Example: `asc`

Headers

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

Errors

400 CATEGORY_LIST_INVALID_LIMIT
Limit must be within the documented list range.
400 INVALID_INPUT
Cursor is malformed or does not match the current list state.
400 CATEGORY_SEARCH_TOO_LONG
Search exceeds the configured maximum length.
400 CATEGORY_LIST_INVALID_SORT_BY
Sort_by is not one of the documented fields.
400 CATEGORY_LIST_INVALID_SORT_DIRECTION
Sort_direction is not asc or desc.
400 CATEGORY_LIST_INVALID_PARENT_ID
Parent_id is neither null nor a positive integer.
400 CATEGORY_LIST_INVALID_ANCESTOR_ID
Ancestor_id is not a positive integer.
400 CATEGORY_LIST_INVALID_BOOLEAN
A boolean list filter is not true or false.
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/categories?ancestor_id=12&cursor=eyJ2IjoxLCJyIjoiY2F0ZWdvcnkifQ&has_children=true&has_images=true&limit=20&parent_id=null&search=apparel&sort_by=name&sort_direction=asc&tree=false' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories?ancestor_id=12&cursor=eyJ2IjoxLCJyIjoiY2F0ZWdvcnkifQ&has_children=true&has_images=true&limit=20&parent_id=null&search=apparel&sort_by=name&sort_direction=asc&tree=false", {
  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/categories?ancestor_id=12&cursor=eyJ2IjoxLCJyIjoiY2F0ZWdvcnkifQ&has_children=true&has_images=true&limit=20&parent_id=null&search=apparel&sort_by=name&sort_direction=asc&tree=false",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "categories": [
      {
        "created_at": "2026-06-09T12:00:00+05:30",
        "description": "Clothing and fashion.",
        "has_children": true,
        "id": 7,
        "image_cdn_url": "",
        "image_id": null,
        "image_url": "",
        "name": "Apparel",
        "parent_id": 12,
        "parent_name": "Collections",
        "product_count": 42,
        "seo_description": "Browse clothing, shoes, and accessories.",
        "seo_title": "Shop Apparel",
        "slug": "apparel",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "storefront_path": "/category/apparel",
        "storefront_url": "https://store.example.com/category/apparel",
        "template_handle": "default_category",
        "updated_at": "2026-06-09T12:00:00+05:30"
      }
    ],
    "has_next": false,
    "has_previous": false,
    "limit": 20,
    "resource_type": "category",
    "sort_by": "name",
    "sort_direction": "asc",
    "total": 1,
    "total_all": 1,
    "truncated": false
  },
  "success": true
}

Search categories

GET read_products

Search categories for picker-style suggestions.

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

Query parameters

Name	Type	Description
`q`	`string`	Search query. Maximum 200 characters. Example: `apparel`
`limit`	`integer`	Suggestion count. Defaults to 10. Maximum 50. Example: `10`

Headers

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

Errors

400 CATEGORY_LIST_INVALID_LIMIT
Limit must be within the documented suggestion range.
400 CATEGORY_SEARCH_TOO_LONG
Q exceeds the configured maximum length.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/search?limit=10&q=apparel", {
  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/categories/search?limit=10&q=apparel",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "items": [
      {
        "id": 7,
        "name": "Apparel",
        "slug": "apparel"
      }
    ],
    "total": 1
  },
  "success": true
}

Get a category

GET read_products

Fetch one category by id.

Returns the category if it belongs to the token's store. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Path parameters

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

Headers

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

Errors

400 STORE_API_INVALID_CATEGORY_ID
Id is not an integer.
404 CATEGORY_NOT_FOUND
Category does not exist in this store.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/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/categories/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": "Clothing and fashion.",
    "has_children": true,
    "id": 7,
    "image_cdn_url": "",
    "image_id": null,
    "image_url": "",
    "name": "Apparel",
    "parent_id": 12,
    "parent_name": "Collections",
    "product_count": 42,
    "seo_description": "Browse clothing, shoes, and accessories.",
    "seo_title": "Shop Apparel",
    "slug": "apparel",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/category/apparel",
    "storefront_url": "https://store.example.com/category/apparel",
    "template_handle": "default_category",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "success": true
}

List category metafields

GET read_products

List a category's custom-data values visible to the calling app.

Returns a paginated list. Definitions are filtered through the calling app's access rules; private app-owned definitions are visible only to their owner. Values are addressed by namespace and key.

Path parameters

Name	Type	Description
`id` required	`integer`	Category 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_CATEGORY_ID
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
Category does not exist in this store.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/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/categories/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 category metafields

PUT write_products

Create, update, or delete category custom-data values.

Send namespace-and-key entries. A string value creates or replaces a value; null or an empty string deletes it. Definition access, type, constraint, reference, translation-staleness, search-index, audit, and webhook rules are applied in the same transaction.

Path parameters

Name	Type	Description
`id` required	`integer`	Category 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":"care","value":"Hand wash"}]`

Errors

400 STORE_API_INVALID_CATEGORY_ID
Id is not a positive integer.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
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
The app-owned definition does not allow Store Admin writes.
404 NOT_FOUND
Category 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/categories/7/metafields' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "metafields": [
    {
      "key": "care",
      "namespace": "details",
      "value": "Hand wash"
    }
  ]
}'

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

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/categories/7/metafields",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "metafields": [{
            "key": "care",
            "namespace": "details",
            "value": "Hand wash",
        }],
    },
)
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 category

POST write_products

Create a category.

Creates a category. name is required; optional text fields, hierarchy assignment, image assignment, and template assignment follow the Category resource contract. If image_id is non-empty, it must point to an upload image in the same store and the token must also have read_files. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply 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`	Category name. Example: `Apparel`
`slug`	`string`	Optional slug. Omit to generate from name. Example: `apparel`
`parent_id`	`integer`	Optional parent category id. Omit or send 0 for a root category. Example: `12`
`description`	`string`	Optional plain-text description. Example: `Clothing and fashion.`
`seo_title`	`string`	Optional SEO title. Omit or send an empty string to let the storefront fall back to the Category name. Example: `Shop Apparel`
`seo_description`	`string`	Optional SEO description. Omit or send an empty string to let the storefront fall back to the Category description. Example: `Browse clothing, shoes, and accessories.`
`image_id`	`string`	Optional Media-library upload image UUID. Non-empty values require `read_files` access to the referenced file. Example: `8f2a1c2b-9d4e-4a56-b789-0123456789ab`
`template_handle`	`string`	Category template assignment. Omit this field, send an empty string, or send `default_category` to use the default Category template. Otherwise, send a Category template handle available in the store's active theme. Example: `default_category`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 STORE_API_CREATE_REDIRECT_UNSUPPORTED
Create_redirect is only supported on update.
400 CATEGORY_NAME_REQUIRED
Name is empty after normalization.
400 CATEGORY_NAME_INVALID_CHARS
Name contains forbidden control characters.
400 CATEGORY_NAME_TOO_LONG
Name exceeds the Category contract max length.
400 CATEGORY_SLUG_INVALID_FORMAT
Slug is not valid for Category URLs.
400 CATEGORY_SLUG_TOO_LONG
Slug exceeds the Category contract max length.
400 CATEGORY_SLUG_GENERATION_FAILED
A slug could not be generated from the supplied name.
400 CATEGORY_UNIQUE_SLUG_GENERATION_FAILED
A unique generated slug could not be allocated.
400 CATEGORY_DESCRIPTION_INVALID_CHARS
Description contains forbidden control characters.
400 CATEGORY_DESCRIPTION_TOO_LONG
Description exceeds the Category contract max length.
400 CATEGORY_SEO_TITLE_INVALID_CHARS
SEO title contains forbidden control characters.
400 CATEGORY_SEO_TITLE_TOO_LONG
SEO title exceeds the Category contract max length.
400 CATEGORY_SEO_DESCRIPTION_INVALID_CHARS
SEO description contains forbidden control characters.
400 CATEGORY_SEO_DESCRIPTION_TOO_LONG
SEO description exceeds the Category contract max length.
400 CATEGORY_DEPTH_EXCEEDED
Parent assignment would exceed the category hierarchy depth limit.
400 CATEGORY_CANNOT_BE_OWN_PARENT
A category cannot be its own parent.
400 CATEGORY_CANNOT_BE_DESCENDANT_PARENT
Parent assignment would create a cycle.
400 CATEGORY_PARENT_NOT_FOUND
Parent category does not exist in this store.
400 TEMPLATE_HANDLE_INVALID
Template handle is not valid for Category templates.
400 TEMPLATE_HANDLE_NOT_FOUND
Template handle does not exist on the store's primary active theme for Category.
400 INVALID_INPUT
Image_id is malformed, is not an image, or is not a merchant upload.
403 STORE_API_SCOPE_REQUIRED
A non-empty image_id requires read_files scope in addition to write_products.
404 NOT_FOUND
Image_id does not reference a file in this store.
404 CATEGORY_NOT_FOUND
Category does not exist in this store.
409 CATEGORY_DUPLICATE
Name already exists under the same parent, or slug already exists in this store.
409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS
A source field cannot be cleared while translations still exist.
400 CATEGORY_PLAN_LIMIT_REACHED
The store has as many categories as its plan allows; the message states the maximum. Fetch /categories/limits for the store's current cap and usage.
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/categories' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Clothing and fashion.",
  "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
  "name": "Apparel",
  "parent_id": 12,
  "seo_description": "Browse clothing, shoes, and accessories.",
  "seo_title": "Shop Apparel",
  "slug": "apparel",
  "template_handle": "default_category"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "description": "Clothing and fashion.",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Apparel",
    "parent_id": 12,
    "seo_description": "Browse clothing, shoes, and accessories.",
    "seo_title": "Shop Apparel",
    "slug": "apparel",
    "template_handle": "default_category"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/categories",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "description": "Clothing and fashion.",
        "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "name": "Apparel",
        "parent_id": 12,
        "seo_description": "Browse clothing, shoes, and accessories.",
        "seo_title": "Shop Apparel",
        "slug": "apparel",
        "template_handle": "default_category",
    },
)
data = res.json()

Response

201

Sample response

{
  "data": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Clothing and fashion.",
    "has_children": false,
    "id": 7,
    "image_cdn_url": "",
    "image_id": null,
    "image_url": "",
    "name": "Apparel",
    "parent_id": 12,
    "parent_name": "Collections",
    "product_count": 0,
    "seo_description": "Browse clothing, shoes, and accessories.",
    "seo_title": "Shop Apparel",
    "slug": "apparel",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/category/apparel",
    "storefront_url": "https://store.example.com/category/apparel",
    "template_handle": "default_category",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "success": true
}

Bulk create categories

POST write_products

Create multiple categories by name.

Creates multiple root categories from names. Slugs are generated automatically; existing names are skipped and reported in skipped. The plan cap applies per row: when the batch would pass it, the rows that fit are created and the response is still 200, with each refused name in row_errors (code CATEGORY_PLAN_LIMIT_REACHED, a localized message and args.max). Check row_errors on every response. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply 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>`	Category names to create. Example: `["Apparel", "Accessories"]`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CATEGORY_BULK_NO_NAMES
No names were provided.
400 CATEGORY_BULK_CREATE_TOO_MANY
Batch exceeds the Category bulk create cap.
400 CATEGORY_NAME_INVALID_CHARS
One name contains forbidden control characters.
400 CATEGORY_NAME_TOO_LONG
One name exceeds the Category contract max length.
400 CATEGORY_SLUG_GENERATION_FAILED
A slug could not be generated from one name.
400 CATEGORY_UNIQUE_SLUG_GENERATION_FAILED
A unique generated slug could not be allocated.
409 CATEGORY_BULK_DUPLICATE
One of the names in the batch was just created by another request.
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/categories/bulk-create' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "Apparel",
    "Accessories"
  ]
}'

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

import requests

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

Response

200

Sample response

{
  "data": {
    "created": [
      {
        "created_at": "2026-06-09T12:00:00+05:30",
        "description": "",
        "has_children": false,
        "id": 7,
        "image_cdn_url": "",
        "image_id": null,
        "image_url": "",
        "name": "Apparel",
        "parent_id": null,
        "parent_name": "",
        "product_count": 0,
        "seo_description": "",
        "seo_title": "",
        "slug": "apparel",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "storefront_path": "/category/apparel",
        "storefront_url": "https://store.example.com/category/apparel",
        "template_handle": "default_category",
        "updated_at": "2026-06-09T12:00:00+05:30"
      }
    ],
    "errors": [],
    "skipped": []
  },
  "success": true
}

Update a category

PUT write_products

Update a category.

Updates provided Category fields. Omitted fields are left unchanged. Sending parent_id: 0 moves the category to the root. Sending an empty image_id clears the image; sending a non-empty image_id requires read_files and the referenced file must be an upload image in the same store. Sending create_redirect can create a slug redirect when the slug changes. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Path parameters

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

Headers

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

Body parameters

Name	Type	Description
`name`	`string`	New Category name. Omit to leave it unchanged; an empty value is invalid. Example: `Apparel`
`slug`	`string`	New slug. Omit to leave the current slug unchanged; send an empty string to regenerate it from the current Category name. Example: `apparel`
`parent_id`	`integer`	New parent category id. Omit to leave it unchanged; send 0 to move the Category to the root. Example: `12`
`description`	`string`	New plain-text description. Omit to leave it unchanged; send an empty string to clear it. Example: `Clothing and fashion.`
`seo_title`	`string`	New SEO title. Omit to leave it unchanged; send an empty string to clear it and restore the storefront Category-name fallback. Example: `Shop Apparel`
`seo_description`	`string`	New SEO description. Omit to leave it unchanged; send an empty string to clear it and restore the storefront Category-description fallback. Example: `Browse clothing, shoes, and accessories.`
`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 Category template assignment. Omit to leave it unchanged, send `default_category` to use the default Category template, or send another Category template handle available in the store's active theme. An empty string is invalid. Example: `default_category`
`create_redirect`	`boolean`	When slug changes, create a redirect from the previous slug. Example: `true`

Errors

409 CATEGORY_CHANGED_DURING_EDIT
The category changed since this edit began. Read it again before saving.
400 STORE_API_INVALID_CATEGORY_ID
Id is not an integer.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CATEGORY_NAME_REQUIRED
Name is empty after normalization.
400 CATEGORY_NAME_INVALID_CHARS
Name contains forbidden control characters.
400 CATEGORY_NAME_TOO_LONG
Name exceeds the Category contract max length.
400 CATEGORY_SLUG_INVALID_FORMAT
Slug is not valid for Category URLs.
400 CATEGORY_SLUG_TOO_LONG
Slug exceeds the Category contract max length.
400 CATEGORY_SLUG_GENERATION_FAILED
A slug could not be generated from the supplied name.
400 CATEGORY_UNIQUE_SLUG_GENERATION_FAILED
A unique generated slug could not be allocated.
400 CATEGORY_DESCRIPTION_INVALID_CHARS
Description contains forbidden control characters.
400 CATEGORY_DESCRIPTION_TOO_LONG
Description exceeds the Category contract max length.
400 CATEGORY_SEO_TITLE_INVALID_CHARS
SEO title contains forbidden control characters.
400 CATEGORY_SEO_TITLE_TOO_LONG
SEO title exceeds the Category contract max length.
400 CATEGORY_SEO_DESCRIPTION_INVALID_CHARS
SEO description contains forbidden control characters.
400 CATEGORY_SEO_DESCRIPTION_TOO_LONG
SEO description exceeds the Category contract max length.
400 CATEGORY_DEPTH_EXCEEDED
Parent assignment would exceed the category hierarchy depth limit.
400 CATEGORY_CANNOT_BE_OWN_PARENT
A category cannot be its own parent.
400 CATEGORY_CANNOT_BE_DESCENDANT_PARENT
Parent assignment would create a cycle.
400 CATEGORY_PARENT_NOT_FOUND
Parent category does not exist in this store.
400 TEMPLATE_HANDLE_INVALID
Template handle is not valid for Category templates.
400 TEMPLATE_HANDLE_NOT_FOUND
Template handle does not exist on the store's primary active theme for Category.
400 INVALID_INPUT
Image_id is malformed, is not an image, or is not a merchant upload.
403 STORE_API_SCOPE_REQUIRED
A non-empty image_id requires read_files scope in addition to write_products.
404 NOT_FOUND
Image_id does not reference a file in this store.
404 CATEGORY_NOT_FOUND
Category does not exist in this store.
409 CATEGORY_DUPLICATE
Name already exists under the same parent, or slug already exists in this store.
409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS
A source field cannot be cleared while translations still exist.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/categories/7' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "create_redirect": true,
  "description": "Clothing and fashion.",
  "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
  "name": "Apparel",
  "parent_id": 12,
  "seo_description": "Browse clothing, shoes, and accessories.",
  "seo_title": "Shop Apparel",
  "slug": "apparel",
  "template_handle": "default_category"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/7", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "create_redirect": true,
    "description": "Clothing and fashion.",
    "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "name": "Apparel",
    "parent_id": 12,
    "seo_description": "Browse clothing, shoes, and accessories.",
    "seo_title": "Shop Apparel",
    "slug": "apparel",
    "template_handle": "default_category"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/categories/7",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "create_redirect": True,
        "description": "Clothing and fashion.",
        "image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "name": "Apparel",
        "parent_id": 12,
        "seo_description": "Browse clothing, shoes, and accessories.",
        "seo_title": "Shop Apparel",
        "slug": "apparel",
        "template_handle": "default_category",
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Clothing and fashion.",
    "has_children": true,
    "id": 7,
    "image_cdn_url": "",
    "image_id": null,
    "image_url": "",
    "name": "Apparel",
    "parent_id": 12,
    "parent_name": "Collections",
    "product_count": 42,
    "seo_description": "Browse clothing, shoes, and accessories.",
    "seo_title": "Shop Apparel",
    "slug": "apparel",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "storefront_path": "/category/apparel",
    "storefront_url": "https://store.example.com/category/apparel",
    "template_handle": "default_category",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "success": true
}

Delete a category

DELETE write_products

Delete a category.

Deletes a category. Subcategories and assigned products block deletion. If collection rules, discounts, or menu items require confirmation, retry with the returned confirmation token.

Path parameters

Name	Type	Description
`id` required	`integer`	Category 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_CATEGORY_ID
Id is not an integer.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CATEGORY_CONFIRMATION_INVALID
Confirmation token is missing, expired, or mismatched.
400 CATEGORY_BULK_DELETE_TOO_MANY
Batch exceeds the Category bulk delete cap.
404 CATEGORY_NOT_FOUND
Category does not exist in this store.
409 CONFIRMATION_REQUIRED
Delete requires confirmation because dependent records will be changed.
409 CATEGORY_HAS_PRODUCTS
Category has assigned products and cannot be deleted.
409 CATEGORY_HAS_SUBCATEGORIES
Category has subcategories and cannot be deleted.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/categories/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/categories/7",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

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

Bulk delete categories

POST write_products

Delete multiple categories.

Send store-scoped integer category ids in category_ids. Categories with subcategories or assigned products are not deleted and appear in failed. If deleting the remaining categories will remove collection rules, discount references, or menu items, the API returns CONFIRMATION_REQUIRED; retry the same ids with confirmed: true and its confirmation_token. The response lists successful ids in deleted. All database changes for those ids commit together.

Headers

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

Body parameters

Name	Type	Description
`category_ids` required	`array<integer>`	Store-scoped integer category 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 is not valid JSON.
400 CATEGORY_BULK_NO_IDS
No category_ids were provided.
409 CATEGORY_BULK_RACED
A category changed during deletion; retry from fresh data.
400 CATEGORY_CONFIRMATION_INVALID
Confirmation token is missing, expired, or mismatched.
400 CATEGORY_BULK_DELETE_TOO_MANY
Batch exceeds the Category bulk delete cap.
404 CATEGORY_NOT_FOUND
Category does not exist in this store.
409 CONFIRMATION_REQUIRED
Delete requires confirmation because dependent records will be changed.
409 CATEGORY_HAS_PRODUCTS
Category has assigned products and cannot be deleted.
409 CATEGORY_HAS_SUBCATEGORIES
Category has subcategories and cannot be deleted.

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

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

import requests

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

Response

200

Sample response

{
  "data": {
    "deleted": [
      7
    ],
    "failed": []
  },
  "success": true
}

Field	Type	Create	Update	Required	Translatable
`id`	id	No	No		No
`store_id`	text	No	No		No
`name`	text	Yes	Yes	create	Yes
`slug`	slug	Yes	Yes		Yes
`parent_id`	integer	Yes	Yes		No
`description`	textarea	Yes	Yes		Yes
`seo_title`	text	Yes	Yes		Yes
`seo_description`	textarea	Yes	Yes		Yes
`image_id`	image	Yes	Yes		No
`image_url`	text	No	No		No
`image_cdn_url`	text	No	No		No
`template_handle`	template	Yes	Yes		No
`create_redirect`	boolean	No	Yes		No
`parent_name`	text	No	No		No
`has_children`	boolean	No	No		No
`product_count`	integer	No	No		No
`created_at`	datetime	No	No		No
`updated_at`	datetime	No	No		No
`storefront_url`	url	No	No	No	No
`storefront_path`	string	No	No	No	No

Category created

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

Fired when a product category is created.

Payload fields

Field	Type	Description
`category.id`	`integer`	Always present
`category.parent_id`	`integer`	Selectable in the Payload builder
`category.name`	`string`	Selectable in the Payload builder
`category.slug`	`string`	Selectable in the Payload builder
`category.description`	`string`	Selectable in the Payload builder
`category.seo_title`	`string`	Selectable in the Payload builder
`category.seo_description`	`string`	Selectable in the Payload builder
`category.image_id`	`string`	Selectable in the Payload builder
`category.image_url`	`string`	Selectable in the Payload builder
`category.image_cdn_url`	`string`	Selectable in the Payload builder
`category.product_count`	`integer`	Selectable in the Payload builder
`category.template_handle`	`string`	Selectable in the Payload builder
`category.parent_name`	`string`	Selectable in the Payload builder
`category.has_children`	`boolean`	Selectable in the Payload builder
`category.created_at`	`string`	Selectable in the Payload builder
`category.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "category": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Clothing and accessories.",
    "has_children": false,
    "id": 5,
    "image_cdn_url": "",
    "image_id": null,
    "image_url": "",
    "name": "Apparel",
    "parent_id": null,
    "parent_name": null,
    "product_count": 0,
    "seo_description": "Shop apparel.",
    "seo_title": "Apparel",
    "slug": "apparel",
    "template_handle": "default_category",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Category updated

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

Fired when a product category is updated.

Payload fields

Field	Type	Description
`category.id`	`integer`	Always present
`category.parent_id`	`integer`	Selectable in the Payload builder
`category.name`	`string`	Selectable in the Payload builder
`category.slug`	`string`	Selectable in the Payload builder
`category.description`	`string`	Selectable in the Payload builder
`category.seo_title`	`string`	Selectable in the Payload builder
`category.seo_description`	`string`	Selectable in the Payload builder
`category.image_id`	`string`	Selectable in the Payload builder
`category.image_url`	`string`	Selectable in the Payload builder
`category.image_cdn_url`	`string`	Selectable in the Payload builder
`category.product_count`	`integer`	Selectable in the Payload builder
`category.template_handle`	`string`	Selectable in the Payload builder
`category.parent_name`	`string`	Selectable in the Payload builder
`category.has_children`	`boolean`	Selectable in the Payload builder
`category.created_at`	`string`	Selectable in the Payload builder
`category.updated_at`	`string`	Selectable in the Payload builder
`changed_fields`	`array`	Always present

Payload shape

Sample payload

{
  "category": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "Clothing and accessories.",
    "has_children": true,
    "id": 5,
    "image_cdn_url": "",
    "image_id": null,
    "image_url": "",
    "name": "Apparel",
    "parent_id": null,
    "parent_name": null,
    "product_count": 87,
    "seo_description": "Shop apparel.",
    "seo_title": "Apparel",
    "slug": "apparel",
    "template_handle": "default_category",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "changed_fields": [
    "title",
    "status"
  ]
}

Category deleted

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

Fired when a product category is deleted.

Payload fields

Field	Type	Description
`category.id`	`integer`	Always present
`category.name`	`string`	Selectable in the Payload builder
`category.slug`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "category": {
    "id": 5,
    "name": "Apparel",
    "slug": "apparel"
  }
}

Category metafield value created

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

Fired when a category metafield value is created.

Payload fields

Field	Type	Description
`category.id`	`integer`	Always present
`category.name`	`string`	Selectable in the Payload builder
`category.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

{
  "category": {
    "id": 5,
    "name": "Apparel",
    "slug": "apparel"
  },
  "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": "How to care for products in this category.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "care",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "Care instructions",
      "namespace": "app:catalog-sync.details",
      "owner_type": "category",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Hand wash"
  }
}

Category metafield value updated

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

Fired when a category 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
`category.id`	`integer`	Always present
`category.name`	`string`	Selectable in the Payload builder
`category.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

{
  "category": {
    "id": 5,
    "name": "Apparel",
    "slug": "apparel"
  },
  "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": "How to care for products in this category.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "care",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "Care instructions",
      "namespace": "app:catalog-sync.details",
      "owner_type": "category",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-10T09:30:00+05:30",
    "value": "Machine wash cold"
  },
  "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": "How to care for products in this category.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "care",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "Care instructions",
      "namespace": "app:catalog-sync.details",
      "owner_type": "category",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Hand wash"
  }
}

Category metafield value deleted

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

Fired when a category metafield value is deleted.

Payload fields

Field	Type	Description
`category.id`	`integer`	Always present
`category.name`	`string`	Selectable in the Payload builder
`category.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

{
  "category": {
    "id": 5,
    "name": "Apparel",
    "slug": "apparel"
  },
  "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": "How to care for products in this category.",
      "id": "6b56de32-3f8c-4a25-a4cb-2d217ad7a8aa",
      "is_translatable": true,
      "key": "care",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "Care instructions",
      "namespace": "app:catalog-sync.details",
      "owner_type": "category",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "Hand wash"
  }
}

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

Payload fields

Payload fields

Payload fields

Possible changed_fields values

Payload fields

Payload fields

Possible `changed_fields` values