---
title: Collection
description: Subscribe to field-level changes on the Collection GraphQL Admin API object.
api_version: unstable
source_url:
  html: 'https://shopify.dev/docs/api/events/latest/collection'
  md: 'https://shopify.dev/docs/api/events/latest/collection.md'
api_name: events
---

# Collection

**Requires \`read\_products\` access scope.:**

Subscribe to field-level changes on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) GraphQL Admin API object. You can subscribe to create, delete, and update events, as well as changes to specific fields.

Each [topic](https://shopify.dev/docs/api/events/latest#configuration) corresponds to a commerce resource (for example, a collection) that can exist independently within its domain. Child entities that depend on a parent within the same domain don't have their own topic. Instead, changes to child entities trigger a delivery on the parent topic. Calculated fields, derived fields, auto-updated timestamps, and cross-domain fields aren't available as triggers.

## shopify.app.toml

```toml
[events]
api_version = "unstable"


[[events.subscription]]
handle = "my_collection_events"


topic = "Collection"
actions = ["update"]
triggers = [
    "collection.title",
    "collection.handle"
]


uri = "https://your-app.com/events"


query = """
query collection_details($collectionId: ID!) {
  collection(id: $collectionId) {
    id
    title
    handle
    sortOrder
  }
  shop {
    id
  }
}
"""


# Optional
query_filter = "collection.handle:'summer-collection'"
```

***

## Supported triggers

Field-level [triggers](https://shopify.dev/docs/api/events/latest#configuration) for `Collection` subscriptions.

All triggers require the [`read_products`](https://shopify.dev/docs/api/usage/access-scopes) access scope, and those triggers that require additional scopes are documented where relevant. Deprecated triggers are listed last.

Subscriptions can include multiple triggers. Use the `shopify-webhook-id` header for deduplication when handling duplicate deliveries.

Custom queries aren't limited to [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection). They can query the full GraphQL Admin API.

### collection

Fires when events involve the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object, which represents a group of [products](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) that merchants can organize to make their stores easier to browse and help customers find related products.

The `"create"` and `"delete"` actions are only relevant within the context of this parent topic. Use `fields_changed` to follow or replicate impacted data after a delete event. Define a custom query to retrieve specific fields from create events.

Collect details about changes to the object by subscribing to the trigger along with the `"update"` action, though it's recommended that you narrow your subscription to one of the other triggers below.

**Variables:** `collectionId`

### collection​.descriptionHtml

Fires when the [`descriptionHtml`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.descriptionHtml) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `descriptionHtml` field represents the description of the collection, including any HTML tags and formatting.

**Variables:** `collectionId`

### collection​.handle

Fires when the [`handle`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.handle) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `handle` field represents a unique string that identifies the collection.

**Variables:** `collectionId`

### collection​.image

Fires when the [`image`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.image) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `image` field represents the image associated with the collection.

**Variables:** `collectionId`

### collection​.metafield

Fires when the [`metafield`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.metafield) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `metafield` field represents a custom field, including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information.

**Variables:** `collectionId`, `metafieldKey`, `metafieldNamespace`

### collection​.metafield​.value

Fires when the [`value`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Metafield#field-Metafield.fields.value) field on the [`Metafield`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Metafield) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `value` field represents the data stored in the metafield.

**Variables:** `collectionId`, `metafieldKey`, `metafieldNamespace`

### collection​.products

Fires when the [`products`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.products) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `products` field represents the products that are included in the collection.

**Variables:** `collectionId`, `productsId`

### collection​.sortOrder

Fires when the [`sortOrder`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.sortOrder) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `sortOrder` field represents the order in which the products in the collection are displayed by default in the Shopify admin and in sales channels, such as an online store.

**Variables:** `collectionId`

### collection​.templateSuffix

Fires when the [`templateSuffix`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.templateSuffix) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `templateSuffix` field represents the suffix of the Liquid template being used to show the collection in an online store.

**Variables:** `collectionId`

### collection​.title

Fires when the [`title`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection#field-Collection.fields.title) field on the [`Collection`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Collection) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `title` field represents the name of the collection.

**Variables:** `collectionId`

### Examples

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["create"]
  triggers = ["collection"]

  uri = "https://your-app.com/events"

  query = """
  query collection_details($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "create",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789']"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: create
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.descriptionHtml"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
      descriptionHtml
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "descriptionHtml": "<p>Example</p>"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].descriptionHtml"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.handle"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].handle"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.image"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
      image {
        id
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "image": {
          "id": "gid://shopify/Image/111"
        }
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].image"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.metafield(namespace: 'custom', key: 'material')"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!, $metafieldNamespace: String!, $metafieldKey: String!) {
    collection(id: $collectionId) {
      id
      title
      handle
      metafield(namespace: $metafieldNamespace, key: $metafieldKey) {
        namespace
        key
        value
        type
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "metafield": {
          "namespace": "custom",
          "key": "material",
          "value": "Cotton",
          "type": "single_line_text_field"
        }
      }
    },
    "fields_changed": [
      "collection.metafield(namespace: 'custom', key: 'material')"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789",
      "metafieldKey": "material",
      "metafieldNamespace": "custom"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.metafield(namespace: 'custom', key: 'material').value"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!, $metafieldNamespace: String!, $metafieldKey: String!) {
    collection(id: $collectionId) {
      id
      title
      handle
      metafield(namespace: $metafieldNamespace, key: $metafieldKey) {
        namespace
        key
        value
        type
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "metafield": {
          "namespace": "custom",
          "key": "material",
          "value": "Cotton",
          "type": "single_line_text_field"
        }
      }
    },
    "fields_changed": [
      "collection.metafield(namespace: 'custom', key: 'material').value"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789",
      "metafieldKey": "material",
      "metafieldNamespace": "custom"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.products"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
      products(first: 10) {
        nodes {
          id
        }
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "products": {
          "nodes": [
            {
              "id": "gid://shopify/Product/111"
            }
          ]
        }
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].products"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789",
      "productsId": "gid://shopify/Product/456"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.sortOrder"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
      sortOrder
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "sortOrder": "…"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].sortOrder"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.templateSuffix"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
      templateSuffix
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection",
        "templateSuffix": "…"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].templateSuffix"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "collection-event"

  topic = "Collection"
  actions = ["update"]
  triggers = ["collection.title"]

  uri = "https://your-app.com/events"

  query = """
  query collection_event_payload($collectionId: ID!) {
    collection(id: $collectionId) {
      id
      title
      handle
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Collection",
    "action": "update",
    "handle": "collection-event",
    "data": {
      "collection": {
        "id": "gid://shopify/Collection/789",
        "title": "Example collection",
        "handle": "example-collection"
      }
    },
    "fields_changed": [
      "collection[id: 'gid://shopify/Collection/789'].title"
    ],
    "query_variables": {
      "collectionId": "gid://shopify/Collection/789"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: collection-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Collection/789
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Collection
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

***