# Shopify Knowledge Patch > Shopify - Skill: `nevaberry/shopify-knowledge-patch` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add nevaberry/shopify-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/shopify-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/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](references/api-versioning-and-access.md) | API lifecycle, access deadlines, versioned surfaces, enforcement, tokens, and mTLS | | [custom-data-and-events.md](references/custom-data-and-events.md) | Customer webhooks, metafields, custom IDs, capabilities, Events, and consent | | [catalog-inventory-and-fulfillment.md](references/catalog-inventory-and-fulfillment.md) | Products, collections, inventory, fulfillment, bundles, and REST image IDs | | [orders-customers-and-subscriptions.md](references/orders-customers-and-subscriptions.md) | Orders, drafts, exchanges, companies, customers, subscriptions, and tax behavior | | [payments-discounts-and-delivery.md](references/payments-discounts-and-delivery.md) | Vaulting, gift cards, discounts, delivery promises, profiles, labels, and pickup | | [storefront-checkout-and-markets.md](references/storefront-checkout-and-markets.md) | Storefront carts, checkout, markets, Hydrogen, UCP, branding, and script tags | | [functions-extensions-and-tooling.md](references/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.