Agent Skills: Shopify Knowledge Patch

Shopify Knowledge Patch

Use this skill for Shopify API integrations, upgrades, app migrations, storefront work, Functions, extensions, inventory, fulfillment, payments, subscriptions, and developer tooling. Read the topic reference that matches the work before changing an integration.

Reference index

| Reference | Topics | | --- | --- | | api-versioning-and-access.md | API lifecycle, access deadlines, versioned surfaces, enforcement, tokens, and mTLS | | custom-data-and-events.md | Customer webhooks, metafields, custom IDs, capabilities, Events, and consent | | catalog-inventory-and-fulfillment.md | Products, collections, inventory, fulfillment, bundles, and REST image IDs | | orders-customers-and-subscriptions.md | Orders, drafts, exchanges, companies, customers, subscriptions, and tax behavior | | payments-discounts-and-delivery.md | Vaulting, gift cards, discounts, delivery promises, profiles, labels, and pickup | | storefront-checkout-and-markets.md | Storefront carts, checkout, markets, Hydrogen, UCP, branding, and script tags | | functions-extensions-and-tooling.md | Functions, POS, UI extensions, Liquid, analytics, App Home, and Partner API tooling |

Breaking changes and migrations

Confirm the effective API version

• Stable versions release quarterly at 17:00 UTC and remain supported for at least 12 months, with at least nine months of overlap between consecutive versions.
• An inaccessible requested version falls forward to the oldest accessible stable version.
• Read X-Shopify-API-Version on responses and versioned webhooks to learn the version Shopify actually used.
• A deprecation explicitly applied to every supported stable version is not deferred by pinning an older version.

Track published version deadlines

| Version | Access ends | | --- | --- | | 2025-07 | 2026-07-16 15:00 UTC | | 2025-10 | 2026-10-16 15:00 UTC | | 2026-01 | 2027-01-16 15:00 UTC | | 2026-04 | 2027-04-16 15:00 UTC | | 2026-07 | 2027-07-16 15:00 UTC | | 2026-10 | 2027-10-16 15:00 UTC | | 2027-01 | 2028-01-16 15:00 UTC |

Continued use of an unsupported resource after its deadline can delist an app and block installs for at least seven days. Admin warnings remain until seven days after the last detected use.

Migrate customer webhooks

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 corresponding topics instead:

• CUSTOMER_TAGS_ADDED and CUSTOMER_TAGS_REMOVED
• CUSTOMERS_EMAIL_MARKETING_CONSENT_UPDATE
• CUSTOMERS_MARKETING_CONSENT_UPDATE
• CUSTOMERS_PURCHASING_SUMMARY

Replace removed customer payment-method 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.

Replace removed metafield contracts

• Replace public PrivateMetafield usage with app-data metafields for app storage or app-reserved namespaces for per-resource data.
• Replace removed MetafieldStorefrontVisibility queries, mutations, and visibleToStorefrontApi fields with reads of MetafieldDefinition.access and writes through metafieldDefinitionUpdate.
• Replace MetafieldDefinitionInput.useAsCollectionCondition with capabilities.smartCollectionCondition.
• Replace removed metafieldDelete(gid) with metafieldsDelete entries containing ownerId, namespace, and key; the mutation does not accept a metafield GID.

Update fulfillment-hold authorization and fields

node and nodes return null for holds outside the app's fulfillment-order scope. The required scopes are read_merchant_managed_fulfillment_orders, read_assigned_fulfillment_orders, read_third_party_fulfillment_orders, and read_marketplace_fulfillment_orders for the corresponding hold owners.

Replace FulfillmentHold.heldBy with heldByApp, or with heldByApp.title when the former string value is needed.

Move company-location tax data

Move company-location tax exemptions and registration IDs to CompanyLocationTaxSettings. Replace the four assign/create/revoke mutations with companyLocationTaxSettingsUpdate; see the orders reference for the exact removed mutation names.

Prepare for script-tag shutdown

• ScriptTagInput.displayScope accepts only ONLINE_STORE and defaults to it.
• Thank you and Order status page script tags were deprecated for August 28, 2025.
• Move checkout UI changes to Checkout Extensions and analytics or conversion tracking to Web Pixels.
• Online Store script tags stop running on March 1, 2027.

Meet access and transport deadlines

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

Handle scheduled schema behavior

• Customer Account API removes Customer.lastIncompleteCheckout and Checkout types in 2026-10.
• Beginning in 2026-10, updating an order shipping address recalculates its taxes.
• GraphQL Admin 2026-10 removes DraftOrderDiscountNotAppliedWarning.priceRule.
• 2026-07 removes DraftOrderLineItem.grams.
• In POS 2026-07, bundle components expose discount allocations and fixed-amount line-item discounts are per unit.

High-value current contracts

Use custom IDs with their present limits

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

Account for product and inventory behavior

• ProductInput.handle is checked for uniqueness when supplied.
• One Storefront product or productByHandle query can request up to 2,000 variants; that limit does not apply across multiple product queries in one request or when variants are reached through another path.
• inventoryLevels and inventoryLevel accept includeInactive, and InventoryLevel.isActive reports the result.
• inventoryActivate preserves the level's available quantity when reactivating it.

Use the revised order and draft contracts

• 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 components.
• CalculateExchangeLineItemInput.variantId selects the exchange variant.

Apply discount and delivery semantics precisely

• App-discount inputs and objects distinguish one-time and subscription applicability, support recurringCycleLimit, and reject both purchase modes set to false.
• App-discount inputs now default appliesOnSubscription to true.
• Multiple product discounts can apply to one cart line, and discounts can target specific markets.
• deliveryPromiseSettings, deliveryPromiseParticipantsUpdate, and delivery_promise_settings/update form the read, write, and webhook contract for delivery-promise configuration.

Follow Function response rules

• Use HttpResponse.header(name: ...) for case-insensitive lookup of one header; the all-header headers field remains but is deprecated.
• For JSON responses, use JSON_body without body. If both are present, body wins; absent Content-Type is filled as application/json.
• Malformed metafield input-query variables raise InvalidVariableValueError rather than behaving as empty input.

Preview and early-access checks

Treat these items according to their stated availability:

• Physical inventory is a feature preview.
• Next Generation Events is a developer preview.
• Liquid block and partial tags are a developer preview.
• Market-driven shipping and its Admin API are a feature preview.
• Mixed shipping and pickup within one order is a feature preview.
• SubscriptionContractCalculation is early access.

Read the topic references before implementing these surfaces; they preserve the available fields, mutations, and migration details without adding unstated behavior.