Shopify Developers Updates & Release Notes

Fewer deliveries, richer payloads, no follow-up queries: Events is a declarative replacement for classic webhooks, now generally available across 18 topics.

With the 2026-10 API version Next Gen Events, Shopify's successor to classic webhooks, is now generally available. Events give you more customization than classic webhooks, letting you choose what changes your app receives, and what data comes with the payload.

If your app keeps track of collection memberships, for example, finding out that a collection changed is only part of the work. You still need to know which product joined or left. With classic webhooks, that can mean fetching the collection's products, comparing them with your saved list, and then updating your app. You're doing all of that work to identify one change.

We built Events to make this easier. Your subscription tells us which changes your app cares about and what data it needs to process them. We send you the change, the affected resource IDs, and the result of your GraphQL query together.

Tell us what your app cares about

You configure Events subscriptions right in your app's shopify.app.toml configuration file. An event has three components:

• triggers: Which changes matter to your app. For example, a product joining or leaving a collection, or a variant's price changing.
• query: What data you need when that happens. Write a GraphQL Admin API query, and we'll include its result in the payload. You can include related data and metafields too.
• query_filter: Which results your app needs to receive. For example, you can limit deliveries to only products with an ACTIVE status.

The trigger and query are independent. A change to one field can trigger a query that fetches the other data your app needs. The query filter then checks that result to decide whether to deliver it. For more on how triggers, queries, and query filters work together, see the Events overview.

Receive the change and the data you need together

Let's continue to use collection memberships as an example. Your app maintains a search index, and you need to update it whenever a product joins or leaves a collection.

You can subscribe to collection.products and use the collection and product IDs directly in your query:

[events]
api_version = "2026-10"

[[events.subscription]]
handle = "collection-membership"
topic = "Collection"
actions = ["update"]
triggers = ["collection.products"]
uri = "/api/events/collections"
query = """
query CollectionMembership($collectionId: ID!, $productsId: ID!) {
  collection(id: $collectionId) {
    id
    hasProduct(id: $productsId)
  }
}
"""

When product 456 is added to collection 123, you receive a payload like this:

{
  "topic": "Collection",
  "action": "update",
  "handle": "collection-membership",
  "data": {
    "collection": {
      "id": "gid://shopify/Collection/123",
      "hasProduct": true
    }
  },
  "fields_changed": {
    "added": ["collection[id: 'gid://shopify/Collection/123'].products[id: 'gid://shopify/Product/456']"],
    "updated": [],
    "removed": []
  },
  "query_variables": {
    "collectionId": "gid://shopify/Collection/123",
    "productsId": "gid://shopify/Product/456"
  }
}

Your app now knows which product joined which collection:

• The action is update because adding a product changes the collection's membership.
• The query tells you that hasProduct is true. That query runs as part of your subscription, so you don't need to make another API call after receiving the delivery or fetch the collection's full product list.
• fields_changed.added tells you what changed.
• query_variables gives you both IDs.

The query result reflects the state when the query runs, so use fields_changed to understand the change and data for the current context. The delivery structure guide has more examples.

More topics to build with

We started the developer preview with Product and Customer. We've expanded our coverage to many more key types across Admin GraphQL:

• Merchandising: Product and Collection
• Customers and companies: Customer and Company
• Orders, fulfillment, and returns: Order, Fulfillment Order, Refund, and Return
• Inventory and locations: Inventory Item, Inventory Shipment, Inventory Transfer, and Location
• Content: Article, Blog, and Page
• Custom data: Metafield Definition, Metaobject, and Metaobject Definition

Each topic has its own supported triggers, query variables, and access scopes. Check the Events API reference for the changes you want to subscribe to.

Get more out of your subscriptions

It can be tempting to copy your existing payload into a GraphQL query and subscribe to every change. That gets you familiar data, but it also carries over a lot of the work your app was already doing.

Start with what your app needs to do when something changes, then shape the subscription around that. In the collection example, we only need the affected membership. Loading every product in the collection on each delivery adds work without helping us process that change.

The Events optimization guide walks through choosing specific triggers, querying the affected resource, and splitting subscriptions while keeping the data your app needs. It also explains the complexity limit Shopify places on your queries and how to check that your queries stay within that limit before releasing your configuration.

As you move over to Events from classic webhooks, measure the deliveries your app receives, the size of each payload, and the follow-up API calls it makes. Those will tell you where the change is helping and where there's more work to do.

Get started

Your existing classic webhook integrations will continue to work. You can use both in the same app and move workflows over one at a time. For topics or subscription patterns Events doesn't support yet, keep using classic webhooks.

• Moving from Webhooks to Events?: We recommend starting with identifying a workflow where your app is receiving a lot of updates and discarding most of them, or making another API call on every delivery. Look at what your handler actually does, which changes it needs, and what data it reads. That gives you the starting point for your subscription. Check out the migration guide to get started.
• Brand new to both classic webhooks and Events?: To get started, use Shopify CLI version 4.83 or later and follow the getting started guide. Set your events API version to 2026-10 and choose the topic and triggers your app needs from the reference.
• Already using the Events developer preview? Just update your events API version from unstable to 2026-10, including any subscription-level overrides. Review the versioned topic reference, then test and deploy the updated configuration.

We'd love to hear what you build with events, and where you're getting stuck. If a missing topic or trigger is blocking your migration, tell us which workflow you're trying to move over in the developer community.

Summary

Apps can now discover Rollouts, inspect their schedules, traffic allocation, and resource changes, and receive notifications when they change. These capabilities help apps understand and respond to coordinated launches, experiments, and temporary events across discounts, catalogs, themes, and checkout and accounts configurations.

What's new

• Discover and read Rollouts. Use the root rollouts query to list and search Rollouts, and rollout(id:) to fetch a Rollout directly by ID.
• See what a Rollout changes. Read how each treatment affects discounts, catalogs, themes, and checkout and accounts configurations.
• Understand schedules and allocation. Read planned activation and conclusion times, configured traffic Allocation, current effective Traffic Allocation, and treatment split values. Configured allocation alone does not determine effective reach.
• Stay up to date. Subscribe to Rollout webhooks for lifecycle, effective-allocation, and resource-change notifications. Refetch affected Rollouts to keep your integration current.

Access Rollout data

Request read_rollouts to access Rollout data. Existing resource scopes apply to the underlying resource payloads, and existing installations may need merchant reauthorization.

See the Rollout API reference for details.

If your app reads discounts, see Update your app to account for discount Rollouts for discount-specific integration guidance and compatibility behavior.

Update your app to account for discount Rollouts

Summary

Admin GraphQL API version 2026-10 adds a read-only rollouts connection across Discount types. Apps that read discounts should use Discount.rollouts alongside existing discount fields to account for Rollout-driven schedules and buyer reach.

What's changing

Merchants can include discounts in Rollouts to coordinate launches, test discounts with a share of buyers, or run temporary events alongside other store changes. When a discount is part of a Rollout, its native dates alone don't describe its availability.

Update your integration

• Request access. Add read_rollouts to your app's scopes. Existing resource scopes still apply to the underlying resource payloads, and existing installations may need merchant reauthorization.
• Read the discount's Rollouts. Query Discount.rollouts to identify which Rollouts affect the discount.
• Combine schedules and availability data. Read Rollout schedule fields alongside the discount's existing startsAt and endsAt fields. Also read effective allocation, treatment splits, and whether each change activates or expires the discount. Configured traffic allocation alone does not determine effective reach.

Account for sales-channel availability

Discounts activated at 100% effective traffic are available across all sales channels, subject to normal discount eligibility rules. Partial-traffic Rollout activation applies on the Online Store only.

Discounts outside Rollouts behave as before.

Earlier API versions

On Admin GraphQL API versions earlier than 2026-10, discounts are filtered out if they are active but may not reach all buyers, or if their status differs from the status inferred from native dates.

See the Discount Rollouts upgrade guide for integration guidance and examples.

To discover Rollouts independently of a discount or receive notifications when they change, see Rollouts queries and webhooks in the Admin GraphQL API.

Line items in Orders webhook payloads now include a selling_plan_id field. This field identifies the selling plan applied to a subscription line item, which helps you avoid extra API calls to look up that information. The change applies to API version 2026-10 and later, and you don’t need to take any action to keep your app working.

Previously, if your app needed to know which selling plan applied to a subscription line item, it had to make a follow-up Admin API call for every order it received. That value now arrives directly in the webhook payload.

In Orders webhook payloads, selling_plan_id contains the ID of the selling plan applied to the line item. It’s null for line items that aren’t part of a subscription.

{
  "line_items": [
    {
      "id": 123456789,
      "selling_plan_id": 987654321
    }
  ]
}

This example shows a line item that includes a selling_plan_id value for a subscription.

This change is available on API version 2026-10 and later. Earlier versions are unaffected, and no action is required.

For details on Orders webhook payloads, see the orders webhooks reference.

As of the 2026-10 GraphQL Admin API version, the PointOfSaleDevice object includes a new fiscalDeviceIdentifier field. This field returns the Shopify-assigned fiscal register identifier (manufacturing number) for a POS device. You only need to adopt it if your app supports in-person fiscal compliance workflows.

What changed

The PointOfSaleDevice object in the GraphQL Admin API now includes a nullable fiscalDeviceIdentifier field. It returns the Shopify-assigned fiscal register identifier for the device, for example Sweden's manufacturing number (tillverkningsnummer) that merchants register with the Swedish Tax Agency (Skatteverket). For details, see the PointOfSaleDevice reference.

The field returns a value only for devices at locations in countries whose fiscal regulations require registering the cash register with the tax authority. Sweden is the first supported country. For all other devices, the field returns null.

Who's affected

Apps that support in-person fiscal compliance workflows, such as fiscal transaction signing and journal reporting in countries that require registered cash registers, can use this field. Apps that don't work with POS fiscal compliance aren't affected and don't need to take action.

What to do

• Query the field on the 2026-10 GraphQL Admin API version:

  query {
    pointOfSaleDevice(id: "gid://shopify/PointOfSaleDevice/123") {
      fiscalDeviceIdentifier
    }
  }
  

  This query returns the fiscal register identifier for the device, or null when the device's location doesn't require one.
• To identify the device that your POS UI extension is running on, use session.deviceId, available in POS UI Extensions API 2026-04 and later, and query the GraphQL Admin API with that ID.
• Treat the value as stable for the lifetime of the device registration, and cache it per device.

Related docs

• PointOfSaleDevice reference
• POS UI Extensions Session API

As of API version 2027-01, the metafieldInteger collection source condition inputs and types is removed from GraphQL Admin API. If you use metafieldInteger to create or read collection source conditions, you need to migrate to metafieldInt before you upgrade to API version 2027-01.

What changed

With metafieldInt, the value field on integer metafield conditions changes type from Int to String, to align with the metafield value field on the Storefront API. For details, see the Storefront Metafield.value field reference.

The following types and fields are replaced:

• Collection Source Inclusion Condition Metafield Integer is replaced by Collection Source Inclusion Condition Metafield Int
• Collection Source Inclusion Condition Metafield Integer Relation is replaced by Collection Source Inclusion Condition Metafield Int Relation
• Collection Source Inclusion Condition Input.metafield Integer is replaced by Collection Source Inclusion Condition Input.metafield Int
• Collection Source Inclusion Condition Update Input.metafield Integer is replaced by Collection Source Inclusion Condition Update Input.metafield Int

The relation enum members are unchanged (EQUALS, GREATER_THAN, LESS_THAN). The behavioral difference is that value is now a String instead of an Int.

Writes

These examples show the required switch from metafieldInteger to metafieldInt and the change in the value literal type.

Before:

conditionsToCreate: [{
metafieldInteger: { definitionId: "gid://shopify/MetafieldDefinition/1", relation: GREATER_THAN, value: 2000 }
}]

After:

conditionsToCreate: [{
metafieldInt: { definitionId: "gid://shopify/MetafieldDefinition/1", relation: GREATER_THAN, value: "2000" }
}]

Reads

This example shows the updated type condition you need to use when you read collection source conditions.

Before:

... on CollectionSourceInclusionConditionMetafieldInteger { relation value }

After:

... on CollectionSourceInclusionConditionMetafieldInt { relation value }

Action required

Before you move to API version 2027-01, you need to:

• Update all Admin GraphQL queries and mutations that reference metafieldInteger to use metafieldInt.
• Ensure all integer metafield condition value fields are strings.

If you don’t update your app before you use API version 2027-01, mutations that send metafieldInteger fail validation, and queries that select Collection Source Inclusion Condition Metafield Integer return errors. You can test metafieldInt behavior on 2026-10 before you upgrade to 2027-01.

metafieldInteger continues to work on API versions up to and including 2026-10. On 2026-10, integer metafield conditions resolve to Collection Source Inclusion Condition Metafield Int when present. In API version 2027-01, metafieldInteger is no longer available.

Related docs

• Collection source inclusion condition inputs
• Collection source inclusion condition update inputs
• Collection source inclusion condition metafield Int type reference
• GraphQL Admin API reference

What changed

Starting in API version 2026-10, the shopifyql Query query in the GraphQL Admin API returns a new parseWarnings field on Shopifyql Query Response. This field surfaces non-fatal issues, such as the use of fields scheduled for deprecation, so you can detect and address them proactively.

shopifyql Query now returns a parseWarnings field alongside your results. The field is always present: it returns a list of warning messages when a successful query has non-fatal issues, and an empty list when there are none.

Unlike parseErrors, which explain why a query failed to run, parseWarnings are only returned on queries that ran successfully, together with tableData. Warnings don’t block execution, but they highlight potential problems you should consider fixing.

Why this matters

Warnings help you identify and resolve issues before they cause failures, such as upcoming deprecations or other changes that could affect your queries in future API versions. By monitoring parseWarnings, you can keep your ShopifyQL queries compatible as the API evolves.

What to do

Add parseWarnings to your shopifyql Query selection set, and check it after a successful query in the same way you already check parseErrors:

query {
  shopifyqlQuery(query: "FROM sales SHOW total_sales SINCE -7d") {
    tableData { columns { name } rows }
    parseWarnings
    parseErrors
  }
}

In this example, parseWarnings will contain any non-fatal warnings related to the query, or an empty list if there are none.

Learn more

• shopifyqlQuery query reference
• ShopifyqlQueryResponse object
• ShopifyQL query language
• API versioning

As of the 2026-10 GraphQL Admin API version, the orderCancel mutation returns a new jobResult field of type OrderCancelJobResult.

Order cancellations run asynchronously. The jobResult field provides a structured, cancellation-specific result, including the cancellation status, any errors, and the affected order. Use this field to check whether the cancellation completed successfully and to handle any errors.

Previously, the mutation only exposed the generic job field, which didn’t include cancellation-specific status or errors. The existing job field is unchanged and continues to work as before, so no action is required for existing integrations.

SMS marketing consent is now available through the new smsMarketingConsent field on the CustomerPhoneNumber object. This field uses the same structured consent model as WhatsApp.

The existing flat SMS marketing consent fields on CustomerPhoneNumber remain available for backward compatibility but are now deprecated. New integrations should use smsMarketingConsent, and existing integrations should plan to migrate to this field.

For field definitions, data structure, and migration details, see the CustomerPhoneNumber object reference in the API documentation.

Starting with API version 2027-01, third-party tax apps will receive Global IDs (GIDs) in tax calculation requests and tax summary webhook payloads for all entity references of the summary section. This aligns with how Partners interact with other Shopify APIs.

These apps can now use the same identifiers across all Shopify endpoints without managing different ID formats for tax-specific integrations.

What's changed

This change affects two key integration points:

Tax calculation requests:

• Customer, Company, Company Location, Product, and Product Variant IDs now use the GID format.

Tax summary webhooks:

• All entity IDs within the summary section (Order, Customer, Product, Product Variant, Sales Agreement, Sale, Line Item, Company, Company Location, Shipping Line, and Tax Line) now use the GID format.
• The webhook payload also includes new admin_graphql_api_id fields at the top level for Tax Summary, Shop, and Order entities.

Changes include:

• Top Level: Adds shop_admin_graphql_api_id and order_admin_graphql_api_id fields (existing shop_id and order_id remain as integers).
• Customer IDs: Changes from "id": "5" to "id": "gid://shopify/Customer/5".
• Product IDs: Changes from "id": "1" to "id": "gid://shopify/Product/1".
• Product Variant IDs: Changes from "id": "1" to "id": "gid://shopify/ProductVariant/1".
• Line Item IDs: Changes from "line_item_id": "5" to "line_item_id": "gid://shopify/LineItem/5".
• Sale IDs: Changes from "id": "9" to "id": "gid://shopify/Sale/9".
• Agreement IDs: Changes from "id": "6" to "id": "gid://shopify/Agreement/6".
• Company IDs: Changes from "id": "3" to "id": "gid://shopify/Company/3".
• Company Location IDs: Changes from "id": "4" to "id": "gid://shopify/CompanyLocation/4".
• Shipping Line IDs: Changes from "id": "4" to "id": "gid://shopify/ShippingLine/4".
• Tax Line IDs: Changes from "id": 6 to "id": "gid://shopify/TaxLine/6".

What you need to do

Update your integrations to handle the GID format when processing tax calculations and webhook payloads in API version 2027-01 and later. The following are some examples:

Tax calculation request

Before (2026-10 and earlier):

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "593934299"
      }
    }
  }
}

After (2027-01):

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "gid://shopify/Customer/593934299"
      }
    }
  }
}

Tax summary webhook

Before (2026-10 and earlier):

{
  "id": 80,
  "shop_id": 1,
  "order_id": 64,
  "summary": {
    "agreements": [
      {
        "id": "82",
        "sales": [
          {
            "id": "106",
            "line_item_id": "76"
          }
        ]
      }
    ]
  }
}

After (2027-01):

{
  "id": 80,
  "admin_graphql_api_id": "gid://shopify/TaxSummary/80",
  "shop_id": 1,
  "shop_admin_graphql_api_id": "gid://shopify/Shop/1",
  "order_id": 64,
  "order_admin_graphql_api_id": "gid://shopify/Order/64",
  "summary": {
    "agreements": [
      {
        "id": "gid://shopify/SalesAgreement/82",
        "sales": [
          {
            "id": "gid://shopify/Sale/106",
            "line_item_id": "gid://shopify/LineItem/76"
          }
        ]
      }
    ]
  }
}

We are introducing the inventory_transfer_id to several inventory_shipment webhook payloads to make it easier for developers to identify which inventory_transfer records, if any, a given shipment is related to. This will ease integration burdens and remove the need for developers to merge the datasets on their end to manually build the links.

What changed

Introduces an inventory_transfer_id field to the payloads of the following...

• inventory_shipments/create
• inventory_shipments/delete
• inventory_shipments/add_items
• inventory_shipments/remove_items
• inventory_shipments/update_item_quantities
• inventory_shipments/mark_in_transit
• inventory_shipments/receive_items
• inventory_shipments/update_tracking

Who's affected

This is an additive change, any adopters of the shipment webhooks, upon updating to 2026-10, will get access to this new field.

As of GraphQL Admin API version 2026-10, functions in the segment query language now use the operators MATCHES / NOT MATCHES instead of = true / = false. For example, the previous query shopify_email.opened() = true would now be represented as shopify_email.opened MATCHES ().

The parameters for each function have also been expanded to use their own operators. For example, the query products_purchased(quantity: 5) = true would now be represented as products_purchased MATCHES (quantity = 5). This expands the functionality of parameters. For example, the following queries were not possible before: products_purchased MATCHES (quantity != 5), products_purchased MATCHES (quantity > 5).

Additionally, the following named dates have been deprecated: 12_months_ago, 90_days_ago, 30_days_ago, 7_days_ago. Instead, the you can use the existing date offsets in your segment queries. For example, the named date 12_months_ago is equivalent to the date offset -12m.

Learn more about customer segment filters in our Help Center.

Apps that create new discount types using Shopify Functions can now register shopify/Discount app intents. This lets Sidekick launch an app’s create and edit flows and promote them in the disambiguation picker.

Apps can register an intent using either of these targets:

• admin.app.intent.link navigates to an existing page in a React Router app.
• admin.app.intent.render renders a focused Admin UI extension inline. This target requires API version 2026-04 or later.

Discounts UI extensions using admin.discount-details.function-settings.render are promoted automatically.

Mobile support: admin.app.intent.link discount flows are currently supported in Shopify admin on the web. App-link discounts can appear in the Shopify mobile app’s discount list, but tapping one doesn’t open the app’s edit flow. Until mobile support is available, merchants should use Shopify admin on the web to open and edit these discounts.

What changed

The shopify/Discount intent now supports create and edit actions for app discount flows.

Registration uses the shopify-intent.json meta-schema and references the shopify/discount.json baseline schema. A match Value on function Id maps each intent to a specific Shopify Function implementation, allowing apps with multiple implementations to register a flow for each one. The intent’s value schema carries the discount GID for edit flows.

When a request doesn’t identify a specific discount type or function implementation, merchants can select from the available flows in the disambiguation picker.

Each registered intent counts toward the per-app intent limit.

The extension.ui.paths property continues to work. However, we encourage apps to declare app intents for deeper Sidekick integration across both create and edit flows.

Who’s affected

This applies to apps that create new discount types using Shopify Functions.

Existing apps continue to work unchanged, and no migration is required. Apps that don’t create Function-backed discount types are unaffected.

Why this matters

Merchants can consistently land in the specialized app flow for the discount type they’re creating or editing instead of being routed to Shopify’s default discount UI.

Apps control which Shopify Function implementations are offered and can use either an existing React Router page or a focused inline UI extension.

What to do

No action is required for existing apps.

To promote a discount flow in Sidekick and the disambiguation picker:

• Build a discounts UI extension, which is promoted automatically.
• Register admin.app.intent.link for an existing React Router discount UI.
• Register admin.app.intent.render to provide a focused inline UI extension.

See Build app actions with Sidekick for configuration examples and the Intents API reference for the complete contract.

More resilient token exchanges when migrating to expiring offline access tokens

When you migrate an app from non-expiring offline tokens to expiring offline access tokens without a user session, you can now recover a lost migration response by retrying the exchange with the original non-expiring token for up to seven days. This reduces how often you need a merchant to reopen the app to restore access, but you don’t need to change existing flows to keep them working.

What changed

When you migrate an existing non-expiring offline token to an expiring offline access token without a user session, an eligible retry using the same original token and client credentials returns the same access-token and refresh-token pair as the initial exchange.

On an eligible retry:

• Shopify returns the same access token and refresh token.
• Shopify extends the access token’s expiry when needed.
• Shopify doesn’t extend the refresh token’s expiry.

Recovery for a particular store and app ends when any of the following is true:

• Seven days have passed since the initial exchange for that original token.
• Your app successfully refreshes the issued pair.
• A later token acquisition for the same store replaces that pair, such as a new authorization code or ID-token exchange.

The original non-expiring token remains invalid for GraphQL Admin API requests after migration.

Who's affected

This change affects apps that migrate existing non-expiring offline tokens without a user session, as described in the guide on migrating existing tokens without a user session.

Why this matters

If your app loses the migration response or fails to store it, you can often recover the access and refresh tokens without requiring the merchant to reopen the app and go through authorization again.

What to do

When you don’t receive or persist the migration response:

• Repeat the same migration request with the original non-expiring token and valid client credentials, within seven days of the initial exchange.
• Persist the returned access token, refresh token, and expiry values together.
• Discard the original non-expiring token so your app doesn’t attempt to use it again.

If a retry returns invalid_subject_token, acquire a new token for that store through ID-token exchange or the authorization code grant and then update your stored credentials accordingly.

Starting with the 2027-01 Admin GraphQL API version, apps can read and write packed product dimensions using Inventory Item Measurement.packed Dimensions and Inventory Item Measurement Input.packed Dimensions in the Admin GraphQL API. Shopify uses these measurements for automatic package selection on eligible multi-item orders.

What changed

The packed Dimensions field returns the packed length, width, height, and unit for an inventory item. Mutations that accept Inventory Item Measurement Input can use the same field to save packed dimensions.

When every item in an eligible multi-item order has packed dimensions, Shopify can select the smallest saved package that fits the items. Shopify uses that package to calculate carrier rates at checkout and when the merchant buys a shipping label.

If dimensions are missing or no saved package fits, Shopify keeps the existing package-selection behavior.

Related docs

• Inventory Item Measurement reference
• Inventory Item Measurement Input reference
• Object Dimensions Input reference