Shopify Knowledge Patch

Shopify Knowledge Patch

Load this skill when work touches Shopify APIs, webhooks, Functions, Liquid, Hydrogen, app or UI extensions, checkout, Customer Accounts, POS, payments, subscriptions, markets, inventory, fulfillment, or commerce data models.

Use the quick references for high-impact migrations and common contract changes. Open the topic reference that matches the work before changing a query, mutation, webhook consumer, extension, or integration.

Reference index

Breaking changes and deadlines

Verify the API version actually served

Stable versions release quarterly at 17:00 UTC, remain supported for at least 12 months, and overlap consecutive versions by at least nine months. A request for an inaccessible version falls forward to the oldest accessible stable version. Read X-Shopify-API-Version on responses and versioned webhooks to identify the version actually used.

Plan around published access deadlines

Pinning an older version does not postpone a deprecation that Shopify applies across every supported stable version. Continued use of an unsupported resource after its deadline can delist an app and block installs for at least seven days.

Migrate customer webhook payloads

In 2025-01, embedded customer payloads omit tags, email_marketing_consent, sms_marketing_consent, last_order_id, last_order_name, total_spent, and orders_count. Consume the dedicated customer tags, marketing-consent, and purchasing-summary webhook topics instead. See the exact topic names in customers, orders, and drafts.

Replace remote credit-card creation

customerPaymentMethodRemoteCreditCardCreate is hidden in 2025-01, requires stripePaymentMethodId, and was scheduled for removal after January 2026. Use customerPaymentMethodRemoteCreate; an invalid customer ID produces a user error.

Remove Customer Account checkout dependencies

Customer Account API removes Customer.lastIncompleteCheckout and the Checkout types in 2026-10. Headless checkout SSO supports the documented sso=silent flow.

Retire script-tag integrations

ScriptTagInput.displayScope accepts only ONLINE_STORE and defaults to it when omitted. Thank you and Order status page script tags were deprecated for August 28, 2025. Online Store script tags stop running on March 1, 2027.

Move checkout UI changes to Checkout Extensions and analytics or conversion tracking to Web Pixels.

Adopt expiring public-app tokens and card-deposit mTLS

All public apps must use expiring offline access tokens starting January 1, 2027. The card-deposit endpoint requires an mTLS certificate.

Update metafield deletion and storefront access

metafieldDelete(gid) was removed. Use metafieldsDelete with entries that identify ownerId, namespace, and key; it does not accept a metafield GID.

The MetafieldStorefrontVisibility object, its queries and mutations, and visibleToStorefrontApi fields were removed. Read MetafieldDefinition.access and change it with metafieldDefinitionUpdate.

Update REST product-image GIDs

REST Admin 2025-01 returns product-image admin_graphql_api_id values as gid://shopify/MediaImage/..., not gid://shopify/ProductImage/.... Migrate with medias.id, not medias.legacy_id or product_images.id. Older API versions retain the old GID.

Account for removed schema members

ShopifyPaymentsBankAccount.accountNumber and routingNumber were removed. Several PriceListUserErrorCode values were also removed; consult API lifecycle and removals for the complete list. ITEM_NOT_STOCKED_AT_LOCATION is no longer an inventory error.

High-use API changes

Authorize fulfillment-hold reads by ownership

node and nodes return null for a fulfillment hold outside the app's fulfillment-order scope. Merchant-managed, app-assigned, third-party, and marketplace holds each require their corresponding read scope. Replace FulfillmentHold.heldBy with heldByApp, using heldByApp.title when the former string value is needed.

Handle multiple holds and SKU sharing

A fulfillment order can have multiple independently releasable holds in 2025-01. fulfillmentServiceCreate defaults permitsSkuSharing to true, unless the input overrides it.

Use the expanded product and variant contracts

productTags, productTypes, and productVendors are root connections with cursor pagination instead of a 250-item cap. ProductInput.handle is checked for uniqueness when supplied. One Storefront product or productByHandle query can request up to 2,000 variants, subject to the path-specific limits in the product reference.

Create orders and control draft pricing

orderCreate accepts order.customer.toUpsert and can attach multiple tracking numbers to each fulfillment. DraftOrderLineItemInput.priceOverride replaces catalog price, requires caller-managed currency conversion, and is stripped from bundles and their components.

Beginning with API version 2026-10, changing an order's shipping address recalculates its taxes.

Use custom IDs within their supported scope

Custom IDs are metafield-backed identifiers for any metafield-capable resource, but lookup by custom ID is limited to products and customers. productSet and unstable customerSet support matching-key upserts, but a custom ID cannot yet be the matching key.

Handle cart addresses, costs, and line identity

CartDelivery.addresses exposes selectable delivery addresses. Cart duty and tax totals on Cart.cost are deprecated because tax and duties are finalized at checkout with full customer context. CartLine.viewKey is readable, and cart-line update and removal mutations can identify lines with view_key.

Apply app discounts with current defaults

App-discount inputs distinguish one-time and subscription applicability and support recurringCycleLimit; setting both purchase modes to false is invalid. appliesOnSubscription now defaults to true. Multiple product discounts can apply to one cart line, and discounts can target markets.

Use current Function response handling

Use HttpResponse.header(name: ...) for a case-insensitive single-header lookup; the all-header headers field is deprecated. For JSON responses, use JSON_body without body: body wins when both are present, and a missing Content-Type is filled as application/json.

Malformed metafield input-query variables raise InvalidVariableValueError instead of being treated as empty.

Feature previews and newer capabilities

Treat items explicitly described as developer preview, feature preview, early access, or unstable according to that stated status.

Commerce and inventory previews

Physical inventory and mixed shipping plus pickup are available as feature previews. Market-driven shipping and its Admin API are also in feature preview. SubscriptionContractCalculation is available in early access.

Events and Liquid previews

Next Generation Events adds field-level trigger control, custom GraphQL payloads, and query-based delivery filters in developer preview. Liquid's developer preview adds block and partial tags for reusable composition.

Platform additions

Shop Campaigns performance data is queryable through ShopifyQL, the GraphQL Admin API exposes analytics metric targets, and App Events adds app usage and performance data to the Dev Dashboard.

Oxygen is available on development stores, Hydrogen can deploy to Vercel, and Storefront Catalog MCP implements UCP while Storefront MCP cart tools are deprecated in favor of UCP Cart MCP.