Partners

Collections

Create, read, update, delete, bulk manage, translate, and subscribe to product collections through the Store API.

Collections require product scopes. Reads use read_products; writes use write_products. Collections support name, slug, description, seo_title, seo_description, image_id, template_handle, match_type, is_active, and rule fields. slug is optional on create and generated from the name when omitted; on update, a supplied slug must be non-empty and valid. Rules can match tag, category, vendor, brand, or product title. Assigning a non-empty image_id also requires read_files for the referenced upload image. On create, omitting template_handle assigns default_collection. Use default_collection for the default Collection template, or pass an alternate Collection template handle configured for the store. Omit template_handle on update to leave the current assignment unchanged; an empty string is invalid. Matching products are added in the background after a create or a change to the rules or match_type: the response returns at once with materializing: true, and until materializing is false, product_count and the collection's products are the last materialized result. materialized_at is when the products were last brought up to date; it is null until the first materialization. AI translation is not exposed through the Store API.

Endpoints#

Collection limits

GET read_products

Fetch Collection limits and per-field constraints.

Returns the per-field maximum lengths, list limits, rule limits, and request caps that apply to Collection endpoints. Fetch this contract instead of hard-coding limits or rule operators. 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.

List collections

GET read_products

List collections for the store.

Returns paginated collections. total counts matching results; store_total counts all collections in the store. Pass returned cursors unchanged and reset pagination when filters or sorting change. 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 collections.list response. Omit for the first page; reset when search, status, or sorting changes.

Example: eyJ2IjoxLCJyIjoiY29sbGVjdGlvbiJ9
limit integer

Page size.

Example: 20
search string

Search collections by name or slug.

Example: summer-sale
status string

Filter by active or inactive.

Example: active
sort_by string

Sort field from the Collection list contract.

Allowed values
nameproduct_countcreated_atupdated_at
Example: name
sort_direction string

Sort direction from the Collection list contract.

Allowed values
ascdesc
Example: asc

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 COLLECTION_LIST_INVALID_LIMIT

    Limit is outside the Collection list range.
  • 400 INVALID_INPUT

    Cursor is malformed or does not match the current search, status, or sorting state.
  • 400 COLLECTION_SEARCH_TOO_LONG

    Search exceeds the contract maximum length.
  • 400 COLLECTION_LIST_INVALID_STATUS

    Status is not active or inactive.
  • 400 COLLECTION_LIST_INVALID_SORT_BY

    Sort_by is not a sortable Collection field.
  • 400 COLLECTION_LIST_INVALID_SORT_DIRECTION

    Sort_direction is not asc or desc.

Search collections

GET read_products

Search collections for picker-style suggestions.

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

Query parameters

Name Type Description
q string

Search query.

Example: summer
limit integer

Suggestion count.

Example: 10
offset integer

Number of suggestions to skip.

Example: 0

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 COLLECTION_LIST_INVALID_LIMIT

    Limit is outside the Collection search range.
  • 400 COLLECTION_SEARCH_TOO_LONG

    Q exceeds the contract maximum length.
  • 400 INVALID_INPUT

    Offset must be zero or greater.

Get a collection

GET read_products

Fetch one collection by id.

Returns the collection 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 uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

List collection metafields

GET read_products

List a collection'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 uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

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_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

Set collection metafields

PUT write_products

Create, update, or delete collection 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 uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

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":"season","value":"Summer"}]

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 404 METAFIELD_DEFINITION_NOT_FOUND

    The namespace and key do not identify an accessible Collection definition.
  • 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.
  • 404 NOT_FOUND

    A file reference names a file that does not exist in this store.
  • 400 INVALID_INPUT

    A file reference names a file that is not an uploaded file.

Create a collection

POST write_products

Create a collection.

Creates a collection. name is required. Omitted is_active defaults to true; send false explicitly to create an inactive collection. Optional text fields, image assignment, template assignment, match type, and rules follow the Collection 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.

Body parameters

Name Type Description
name required string

Collection name.

Example: Summer Sale
slug string

Optional slug. Omit to generate from name.

Example: summer-sale
description string

Optional plain-text description.

Example: Seasonal products for summer campaigns.
seo_title string

Optional SEO title.

Example: Summer Sale
seo_description string

Optional SEO description.

Example: Shop products in the Summer Sale collection.
image_id string

Optional Media-library upload image UUID. Non-empty values require read_files access to the referenced file; site assets and non-image uploads are rejected.

Example: 8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_collection. Use default_collection for the default Collection template, or pass an alternate Collection template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_collection to reset it to default, and do not send an empty string.

Example: default_collection
match_type string

all requires every rule to match; any requires at least one rule.

Example: all
is_active boolean

Whether the collection is visible on the storefront. Defaults to true when omitted during creation.

Example: true
rules array<object>

Automatic collection rules. Each rule has field, operator, optional value, and include_subcategories.

Example: [{"field":"tag","operator":"equals","value":"7"}]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is invalid or contains an unknown field.
  • 400 STORE_API_CREATE_REDIRECT_UNSUPPORTED

    Create_redirect is only supported when updating a collection.
  • 400 COLLECTION_NAME_REQUIRED

    Name is empty after normalization.
  • 400 COLLECTION_NAME_TOO_LONG

    Name exceeds the Collection contract max length.
  • 400 COLLECTION_NAME_INVALID_CHARS

    Name contains unsupported control characters.
  • 400 COLLECTION_DESCRIPTION_TOO_LONG

    Description exceeds the Collection contract max length.
  • 400 COLLECTION_SEO_TITLE_TOO_LONG

    SEO title exceeds the Collection contract max length.
  • 400 COLLECTION_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Collection contract max length.
  • 400 COLLECTION_SLUG_REQUIRED

    A provided update slug is empty after normalization.
  • 400 COLLECTION_SLUG_TOO_LONG

    Slug exceeds the Collection contract max length.
  • 400 COLLECTION_SLUG_INVALID_FORMAT

    Slug is not valid for Collection URLs.
  • 400 COLLECTION_SLUG_GENERATION_FAILED

    A slug could not be generated from the supplied name.
  • 400 COLLECTION_MATCH_TYPE_INVALID

    Match type is not valid.
  • 400 COLLECTION_RULES_LIMIT_REACHED

    Rule count exceeds the Collection rule cap.
  • 400 COLLECTION_LIMIT_REACHED

    Store collection cap has been reached.
  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Collection templates.
  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Collection.
  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    A non-empty image_id requires read_files scope in addition to write_products.
  • 400 INVALID_INPUT

    Image_id is malformed, is not an image, or is not a Media-library upload.
  • 404 NOT_FOUND

    Image_id does not reference a file in this store.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 COLLECTION_SLUG_DUPLICATE

    Slug already exists in this store.
  • 400 COLLECTION_PLAN_LIMIT_REACHED

    This store is at its plan collection cap.

Update a collection

PUT write_products

Update a collection.

Updates provided Collection fields. Omitted fields are left unchanged. 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 uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name string

Collection name.

Example: Summer Sale
slug string

New slug. Omit to leave the current slug unchanged; an empty value is invalid.

Example: summer-sale
description string

Optional plain-text description.

Example: Seasonal products for summer campaigns.
seo_title string

Optional SEO title.

Example: Summer Sale
seo_description string

Optional SEO description.

Example: Shop products in the Summer Sale collection.
image_id string

Optional Media-library upload image UUID. Non-empty values require read_files access to the referenced file; site assets and non-image uploads are rejected.

Example: 8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_collection. Use default_collection for the default Collection template, or pass an alternate Collection template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_collection to reset it to default, and do not send an empty string.

Example: default_collection
match_type string

all requires every rule to match; any requires at least one rule.

Example: all
is_active boolean

Whether the collection is visible on the storefront. Defaults to true when omitted during creation.

Example: true
rules array<object>

Automatic collection rules. Each rule has field, operator, optional value, and include_subcategories.

Example: [{"field":"tag","operator":"equals","value":"7"}]
create_redirect boolean

When slug changes, create a redirect from the previous slug.

Example: true

Errors

  • 409 COLLECTION_CHANGED_DURING_EDIT

    The collection changed since this edit began. Read it again before saving.
  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is invalid or contains an unknown field.
  • 400 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS

    Clearing a source field is blocked while translated values exist.
  • 400 COLLECTION_NAME_REQUIRED

    Name is empty after normalization.
  • 400 COLLECTION_NAME_TOO_LONG

    Name exceeds the Collection contract max length.
  • 400 COLLECTION_NAME_INVALID_CHARS

    Name contains unsupported control characters.
  • 400 COLLECTION_DESCRIPTION_TOO_LONG

    Description exceeds the Collection contract max length.
  • 400 COLLECTION_SEO_TITLE_TOO_LONG

    SEO title exceeds the Collection contract max length.
  • 400 COLLECTION_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Collection contract max length.
  • 400 COLLECTION_SLUG_REQUIRED

    A provided update slug is empty after normalization.
  • 400 COLLECTION_SLUG_TOO_LONG

    Slug exceeds the Collection contract max length.
  • 400 COLLECTION_SLUG_INVALID_FORMAT

    Slug is not valid for Collection URLs.
  • 400 COLLECTION_SLUG_GENERATION_FAILED

    A slug could not be generated from the supplied name.
  • 400 COLLECTION_MATCH_TYPE_INVALID

    Match type is not valid.
  • 400 COLLECTION_RULES_LIMIT_REACHED

    Rule count exceeds the Collection rule cap.
  • 400 COLLECTION_LIMIT_REACHED

    Store collection cap has been reached.
  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Collection templates.
  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Collection.
  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    A non-empty image_id requires read_files scope in addition to write_products.
  • 400 INVALID_INPUT

    Image_id is malformed, is not an image, or is not a Media-library upload.
  • 404 NOT_FOUND

    Image_id does not reference a file in this store.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 COLLECTION_SLUG_DUPLICATE

    Slug already exists in this store.

Delete a collection

DELETE write_products

Delete a collection.

Deletes a collection. If catalog links, discount targeting, menu items, or other dependent records require confirmation, retry with the returned confirmation token.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

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_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 COLLECTION_CONFIRMATION_INVALID

    Confirmation token is missing, expired, or mismatched.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 CONFIRMATION_REQUIRED

    Delete requires confirmation because dependent records will be changed.

Bulk delete collections

POST write_products

Delete multiple collections.

Send collection UUIDs in collection_ids. If discount targeting or menu items will be changed, the API returns CONFIRMATION_REQUIRED; retry the exact same ids with confirmed: true and its confirmation_token. A dependency-free selection deletes immediately. This operation is all-or-nothing: every requested collection must still exist and pass validation at commit time. A successful response returns the number deleted.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
collection_ids required array<string>

Collection UUIDs to delete.

Example: ["5ff7d4ea-3250-4a4d-9d26-07f64d917d31", "af720cef-7f1b-40f4-a5f8-8a55ea5b0d84"]
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.
  • 409 COLLECTION_BULK_RACED

    Delete impact changed during the transaction; retry with fresh data.
  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 COLLECTION_CONFIRMATION_INVALID

    Confirmation token is missing, expired, or mismatched.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 CONFIRMATION_REQUIRED

    Delete requires confirmation because dependent records will be changed.

Bulk activate collections

POST write_products

Activate or deactivate multiple collections.

Updates storefront visibility for multiple collections.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
collection_ids required array<string>

Collection UUIDs to update.

Example: ["5ff7d4ea-3250-4a4d-9d26-07f64d917d31"]
is_active required boolean

Target storefront visibility.

Example: true

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 COLLECTION_BULK_UPDATE_TOO_MANY

    Batch exceeds the Collection bulk update cap.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

List collection products

GET read_products

List product ids matched by a collection.

Returns cursor-paginated ids of products currently in this collection. Pass returned cursors unchanged and reset pagination when search or page size changes.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Query parameters

Name Type Description
cursor string

Opaque cursor from this collection's previous response. Omit for the first page; reset when search or page size changes.
limit integer

Page size.

Example: 20

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

List collection product details

GET read_products

List display-ready products matched by a collection.

Returns cursor-paginated product rows from the materialized collection, including title, slug, SKU, type, and image URL. Pass returned cursors unchanged; reset when search or page size changes. Use search to filter by product title or SKU.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Query parameters

Name Type Description
cursor string

Opaque cursor from this collection's previous response. Omit for the first page; reset when search or page size changes.
limit integer

Page size.

Example: 20
search string

Filter products by title or SKU.

Example: summer

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

List collection rules

GET read_products

List rules for a collection.

Returns automatic matching rules for this collection.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.

Add collection rule

POST write_products

Add a rule to a collection.

Adds one automatic matching rule, then updates which products the collection includes.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
field required string

Rule field: tag, category, vendor, brand, or title.

Example: tag
operator required string

Rule operator allowed for the field.

Example: equals
value string

Rule value. Required for value-bearing operators.

Example: 7
include_subcategories boolean

Only valid for category rules.

Example: false

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 COLLECTION_RULES_LIMIT_REACHED

    Rule count exceeds the Collection rule cap.
  • 400 COLLECTION_RULE_FIELD_INVALID

    Rule field is not valid.
  • 400 COLLECTION_RULE_OPERATOR_INVALID

    Rule operator is not valid for the selected field.
  • 400 COLLECTION_RULE_VALUE_REQUIRED

    This rule operator requires a value.
  • 400 COLLECTION_RULE_SUBCATEGORIES_NOT_ALLOWED

    Include_subcategories is only valid for category rules.
  • 400 COLLECTION_RULE_TAG_ID_INVALID

    Tag value is not a valid integer id.
  • 400 COLLECTION_RULE_CATEGORY_ID_INVALID

    Category value is not a valid integer id.
  • 400 COLLECTION_RULE_VENDOR_ID_INVALID

    Vendor value is not a valid integer id.
  • 400 COLLECTION_RULE_BRAND_ID_INVALID

    Brand value is not a valid integer id.
  • 400 COLLECTION_RULE_TITLE_TOO_LONG

    Title rule value exceeds the contract max length.
  • 400 COLLECTION_RULE_TAG_NOT_FOUND

    Referenced tag does not exist in this store.
  • 400 COLLECTION_RULE_CATEGORY_NOT_FOUND

    Referenced category does not exist in this store.
  • 400 COLLECTION_RULE_VENDOR_NOT_FOUND

    Referenced vendor does not exist in this store.
  • 400 COLLECTION_RULE_BRAND_NOT_FOUND

    Referenced brand does not exist in this store.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 COLLECTION_RULE_DUPLICATE

    The rule already exists on this collection.

Update collection rule

PUT write_products

Update a rule on a collection.

Updates one automatic matching rule, then updates which products the collection includes.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
rule_id required uuid

Rule id.

Example: 8d8c22a3-7cf8-4d2c-a54b-45fa63693e83

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
field required string

Rule field: tag, category, vendor, brand, or title.

Example: tag
operator required string

Rule operator allowed for the field.

Example: equals
value string

Rule value. Required for value-bearing operators.

Example: 7
include_subcategories boolean

Only valid for category rules.

Example: false

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 COLLECTION_RULES_LIMIT_REACHED

    Rule count exceeds the Collection rule cap.
  • 400 COLLECTION_RULE_FIELD_INVALID

    Rule field is not valid.
  • 400 COLLECTION_RULE_OPERATOR_INVALID

    Rule operator is not valid for the selected field.
  • 400 COLLECTION_RULE_VALUE_REQUIRED

    This rule operator requires a value.
  • 400 COLLECTION_RULE_SUBCATEGORIES_NOT_ALLOWED

    Include_subcategories is only valid for category rules.
  • 400 COLLECTION_RULE_TAG_ID_INVALID

    Tag value is not a valid integer id.
  • 400 COLLECTION_RULE_CATEGORY_ID_INVALID

    Category value is not a valid integer id.
  • 400 COLLECTION_RULE_VENDOR_ID_INVALID

    Vendor value is not a valid integer id.
  • 400 COLLECTION_RULE_BRAND_ID_INVALID

    Brand value is not a valid integer id.
  • 400 COLLECTION_RULE_TITLE_TOO_LONG

    Title rule value exceeds the contract max length.
  • 400 COLLECTION_RULE_TAG_NOT_FOUND

    Referenced tag does not exist in this store.
  • 400 COLLECTION_RULE_CATEGORY_NOT_FOUND

    Referenced category does not exist in this store.
  • 400 COLLECTION_RULE_VENDOR_NOT_FOUND

    Referenced vendor does not exist in this store.
  • 400 COLLECTION_RULE_BRAND_NOT_FOUND

    Referenced brand does not exist in this store.
  • 404 COLLECTION_NOT_FOUND

    Collection does not exist in this store.
  • 409 COLLECTION_RULE_DUPLICATE

    The rule already exists on this collection.
  • 400 STORE_API_INVALID_COLLECTION_RULE_ID

    Rule id is not a valid UUID.

Delete collection rule

DELETE write_products

Delete a rule from a collection.

Deletes one automatic matching rule, then updates which products the collection includes.

Path parameters

Name Type Description
id required uuid

Collection id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
rule_id required uuid

Rule id.

Example: 8d8c22a3-7cf8-4d2c-a54b-45fa63693e83

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_COLLECTION_ID

    Collection id is not a valid UUID.
  • 400 STORE_API_INVALID_COLLECTION_RULE_ID

    Rule id is not a valid UUID.
  • 404 COLLECTION_NOT_FOUND

    Collection or rule does not exist in this store.

Fields#

Field

Type

Create

Update

Required

Translatable

name

text

Yes

Yes

create

Yes

slug

slug

Yes

Yes

Yes

description

textarea

Yes

Yes

Yes

seo_title

text

Yes

Yes

Yes

seo_description

textarea

Yes

Yes

Yes

image_id

image

Yes

Yes

No

template_handle

template

Yes

Yes

No

match_type

select

Yes

Yes

No

is_active

boolean

Yes

Yes

No

create_redirect

boolean

No

Yes

No

product_count

integer

No

No

No

materializing

boolean

No

No

No

materialized_at

datetime

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

Webhook events#

Subscribe to these events to keep your integration in sync with collections. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.

Metafield events are filtered for every subscriber. An app receives events for definitions it owns. With the event's required scope, it also receives merchant-owned definitions and definitions shared by another app through app_access: shared; another app's private definitions are not delivered. A store-level webhook endpoint receives merchant-owned definitions and app-owned definitions unless merchant_access is hidden. If an event cannot identify the definition owner or its access settings, Tringify does not deliver it.

Collection created

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

Fired when a collection is created.

Payload fields

Field Type Description
collection.id string Always present
collection.name string Selectable in the Payload builder
collection.slug string Selectable in the Payload builder
collection.description string Selectable in the Payload builder
collection.image_id string Selectable in the Payload builder
collection.image_url string Selectable in the Payload builder
collection.image_cdn_url string Selectable in the Payload builder
collection.seo_title string Selectable in the Payload builder
collection.seo_description string Selectable in the Payload builder
collection.template_handle string Selectable in the Payload builder
collection.match_type string Selectable in the Payload builder
collection.is_active boolean Selectable in the Payload builder
collection.product_count integer Selectable in the Payload builder
collection.materialized_at string Selectable in the Payload builder
collection.created_at string Selectable in the Payload builder
collection.updated_at string Selectable in the Payload builder
collection.rules[*].id string Selectable in the Payload builder
collection.rules[*].collection_id string Selectable in the Payload builder
collection.rules[*].field string Selectable in the Payload builder
collection.rules[*].operator string Selectable in the Payload builder
collection.rules[*].value string Selectable in the Payload builder
collection.rules[*].value_label string Selectable in the Payload builder
collection.rules[*].include_subcategories boolean Selectable in the Payload builder

Collection updated

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

Fired when a collection is updated — including rule changes and image 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.

description image_id is_active match_type memberships name rules seo_description seo_title slug template_handle

Payload fields

Field Type Description
collection.id string Always present
collection.name string Selectable in the Payload builder
collection.slug string Selectable in the Payload builder
collection.description string Selectable in the Payload builder
collection.image_id string Selectable in the Payload builder
collection.image_url string Selectable in the Payload builder
collection.image_cdn_url string Selectable in the Payload builder
collection.seo_title string Selectable in the Payload builder
collection.seo_description string Selectable in the Payload builder
collection.template_handle string Selectable in the Payload builder
collection.match_type string Selectable in the Payload builder
collection.is_active boolean Selectable in the Payload builder
collection.product_count integer Selectable in the Payload builder
collection.materialized_at string Selectable in the Payload builder
collection.created_at string Selectable in the Payload builder
collection.updated_at string Selectable in the Payload builder
collection.rules[*].id string Selectable in the Payload builder
collection.rules[*].collection_id string Selectable in the Payload builder
collection.rules[*].field string Selectable in the Payload builder
collection.rules[*].operator string Selectable in the Payload builder
collection.rules[*].value string Selectable in the Payload builder
collection.rules[*].value_label string Selectable in the Payload builder
collection.rules[*].include_subcategories boolean Selectable in the Payload builder
changed_fields array Always present

Collection deleted

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

Fired when a collection is deleted.

Payload fields

Field Type Description
collection.id string Always present
collection.name string Selectable in the Payload builder
collection.slug string Selectable in the Payload builder

Collection metafield value created

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

Fired when a collection metafield value is created.

Payload fields

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

Collection metafield value updated

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

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

Collection metafield value deleted

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

Fired when a collection metafield value is deleted, including when its collection is deleted.

Payload fields

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

Last updated Oct 21, 2026