--- title: 2025-01 release notes description: Update your app from API version 2024-10 to 2025-01. api_name: release-notes source_url: html: 'https://shopify.dev/docs/api/release-notes/2025-01' md: 'https://shopify.dev/docs/api/release-notes/2025-01.md' --- ExpandOn this page * [Highlights](https://shopify.dev/docs/api/release-notes/2025-01.md#highlights) * [Breaking changes](https://shopify.dev/docs/api/release-notes/2025-01.md#breaking-changes) * [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#graphql-admin-api-changes) * [Shopify Function APIs changes](https://shopify.dev/docs/api/release-notes/2025-01.md#shopify-function-apis-changes) * [Payments Apps API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#payments-apps-api-changes) * [Storefront API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#storefront-api-changes) * [REST Admin API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#rest-admin-api-changes) # 2025-01 release notes Note We're no longer publishing API release notes. Instead, you can find the latest updates on Shopify APIs in our [developer changelog](https://shopify.dev/changelog). You can filter updates by area. For example, you can filter API updates by the API name and version, such as GraphQL Admin API changes in version 2025-04. | Release date | Date version is no longer supported | | - | - | | January 1, 2025 | January 1, 2026 | *** ## Highlights Here are some highlights of version 2025-01 of Shopify's APIs: * **Automatic discounts**: The `minimumRequirement` field for both the [`DiscountAutomaticBasic`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticBasic) and [`DiscountAutomaticFreeShipping`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticFreeShipping) objects is now nullable, making minimum purchase conditions optional for automatic discounts. * **Bulk query operations**: The [`BulkOperationUserError`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError) object has been updated with a new `UserError` GraphQL object type, which includes an additional `code` field. * **Fulfillment holds**: You can now place multiple holds on a fulfillment order. Each hold captures a specific issue independently, allowing you to release holds individually while maintaining other active holds. For detailed information on the changes, and how to upgrade to the 2025-01 version of the GraphQL Admin API, consult the [developer changelog](https://shopify.dev/changelog/apply-multiple-holds-to-a-single-fulfillment-order). * **Fulfillment services**: The default value for the `permitsSkuSharing` field on the [`fulfillmentServiceCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentService) mutation is now set to `true`, allowing fulfillment services to stock inventory across multiple locations. * **JSON body support**: We now provide native support of a HTTP request body as a `JSON_body` for function external calls. Use this field when the `body` is in JSON format to reduce function instruction consumption and to ensure the `body` is formatted in logs. Don't use the `JSON_body` field together with the `body` field in the [`HttpResponse`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql/common-objects/httpresponse) object. If both are provided, then the `HttpResponse`'s `body` field takes precedence. If the `JSON_body` field is specified and no `Content-Type` header is included, then the header will automatically be set to `application/json`. * **Metafield admin access**: The `admin` field on the [`MetafieldAccessInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessInput#field-admin) and [`MetafieldAccessUpdateInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessUpdateInput#field-admin) objects is now optional. In API version 2024-10 and prior, this field was required. * **Metafield storefront visibility**: Several related objects, mutations, queries, and fields have been removed. Use the `access` field on the [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldDefinition) object instead. * **Multi-location shop feature**: The deprecated `multiLocation` field has been removed from the [`ShopFeatures`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ShopFeatures) object. Use the [`locationsCount`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/locationsCount) query to determine the number of shop locations. * **New metafieldsDelete mutation**: We've replaced the [`metafieldDelete`](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDelete) mutation with the [`metafieldsDelete`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/metafieldsDelete) mutation. This change provides a fundamental update in how you delete metafields. By using `metafieldsDelete`, you need to adjust your code to accommodate for a new identifier format. * **Product handle uniqueness validation**: The `handle` field on the [`ProductInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ProductInput) input object is now validated for uniqueness, preventing collisions when creating or updating product handles. *** ## Breaking changes These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version. ### Automatic discounts We've changed the [`minimumRequirement`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticBasic#field-minimumrequirement) field for both the [`DiscountAutomaticBasic`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticBasic) object and [`DiscountAutomaticFreeShipping`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticFreeShipping) object to be nullable. Previously, merchants were required to specify minimum purchase conditions on product, order, and free shipping automatic discounts. We're now making these conditions optional, so the [`minimumRequirement`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticFreeShipping#field-minimumrequirement) field can return a `null` value. ### Bulk query operations In the Admin API, we have improved the [`BulkOperationUserError`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError) object by introducing a new [`code`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError#field-code) field for the `userErrors` returned by the [`bulkOperationRunQuery`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/bulkOperationRunQuery#field-bulkoperationrunquerypayload-usererrors) mutation. The new `code` field allows for improved error handling while retaining all the previous fields. We have also made the [`BulkOperationUserError`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError) type public, enabling developers to access this updated error information. ### Customer payloads in webhook topics We've changed how a customer is represented in webhooks: * Removed the `tags` field. Use the [`CUSTOMER_TAGS_ADDED`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customertagsadded) and [`CUSTOMER_TAGS_REMOVED`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customertagsremoved) webhook topics instead. * Removed the `email_marketing_consent` field. Use the [`CUSTOMERS_EMAIL_MARKETING_CONSENT_UPDATE`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customersemailmarketingconsentupdate) webhook topic instead. * Removed the `sms_marketing_consent` field. Use the [`CUSTOMERS_MARKETING_CONSENT_UPDATE`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customersmarketingconsentupdate) webhook topic instead. * Removed the `last_order_id`, `last_order_name`, `total_spent`, and `orders_count` fields. Use the [`CUSTOMERS_PURCHASING_SUMMARY`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customerspurchasingsummary) webhook topic instead. The following [webhook topics](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic) contain a customer payload: * `CHECKOUTS_CREATE` * `CHECKOUTS_UPDATE` * `CUSTOMERS_CREATE` * `CUSTOMERS_DELETE` * `CUSTOMERS_DISABLE` * `CUSTOMERS_ENABLE` * `CUSTOMERS_UPDATE` * `DRAFT_ORDERS_CREATE` * `DRAFT_ORDERS_UPDATE` * `ORDERS_CANCELLED` * `ORDERS_CREATE` * `ORDERS_FULFILLED` * `ORDERS_PAID` * `ORDERS_PARTIALLY_FULFILLED` * `ORDERS_UPDATED` ### Customer payment methods We've hidden the [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreditCardCreate) mutation, as it has been deprecated for more than three years. You can use the [`customerPaymentMethodRemoteCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreate) mutation instead to manage customer payment methods. Learn more about [payment processing](https://shopify.dev/docs/apps/build/payments/processing). **Developer action required** * The [`stripePaymentMethodId`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerpaymentmethodremotecreditcardcreate#argument-stripepaymentmethodid) argument is now required. Update your code to accommodate this change. * Transition away from using the [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerpaymentmethodremotecreditcardcreate) mutation by January 2026. We'll fully remove this mutation after January 2026, following its complete deprecation in the 2025-01 API version. This mutation was primarily intended for creating payment methods using credit cards stored by Stripe. If the customer IDs you request are invalid, then the method returns a user error. ### Fulfillment hold access We've introduced validation for fulfillment hold access in node queries. This change only affects apps which fetch fulfillment holds using a [`node` or `nodes` GraphQL query](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#interface-node). If your app doesn't currently have sufficient access scopes as defined below then you need to request the correct access scopes before migrating to the 2025-01 API version. When using a `node` or `nodes` query to fetch holds, if your app doesn't have sufficient access, then a `null` value is returned for any fulfillment holds that you don't have access to. Refer to the API access scopes section of the [`FulfillmentOrder`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentOrder) object for more information about access scopes. **Developer action required** Apps using the `node` or `nodes` GraphQL queries to fetch fulfillment holds will only retrieve those associated with fulfillment orders for which they have access: | Access scope | What you can access | | - | - | | `read_merchant_managed_fulfillment_orders` | Holds on fulfillment orders assigned to a merchant-managed location | | `read_assigned_fulfillment_orders` | Holds on fulfillment orders assigned to locations owned by your app | | `read_third_party_fulfillment_orders` | Holds on fulfillment orders assigned to a third-party location | | `read_marketplace_fulfillment_orders` | Holds on fulfillment orders that belong to one of your marketplace's orders | For more information, refer to the [changelog](https://shopify.dev/changelog/update-to-fulfillmenthold-heldbyapp-field-from-fulfillmenthold-heldby-field). ### Fulfillment hold field replacement We've added the new [`heldByApp`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#field-heldbyapp) object field on the [FulfillmentHold](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#top) object, replacing the [`heldBy`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/FulfillmentHold#field-heldby) string field. **Developer action required** The [`heldByApp`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#field-heldbyapp) field provides access to all attributes of the [`App`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/App) object, in contrast to the deprecated `heldBy` field, which only indicated the app's title. If you currently query `fulfillmentHold.heldBy`, then transition to querying `fulfillmentHold.heldByApp.title`. ### Fulfillment holds You can now place multiple holds on a fulfillment order. Each hold captures a specific issue independently, allowing you to release holds individually while maintaining other active holds. For detailed information on the changes, and how to upgrade to the 2025-01 version of the GraphQL Admin API, consult the [developer changelog](https://shopify.dev/changelog/apply-multiple-holds-to-a-single-fulfillment-order). ### Fulfillment services The default value of the [`permitsSkuSharing`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentService#field-permitsskusharing) field on the [`fulfillmentServiceCreate` mutation](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentService#top) is now `true`. If `permitsSkuSharing` is `true`, then a fulfillment service can stock inventory at multiple fulfillment services or merchant-managed locations. ### Gift card visibility We've changed the `paymentMethods` field within the [`Input`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/input) object of the [`PaymentCustomizationApi`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql). This feature enhances the flexibility of payment processing by enabling merchants to configure the visibility of gift cards based on specific conditions. Note The [`PaymentCustomizationPaymentMethodPlacement`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/common-objects/paymentcustomizationpaymentmethodplacement) enum contains the `PAYMENT_METHOD` values. ### Localized fields You can now use [localized fields](https://shopify.dev/docs/apps/build/markets/add-locally-required-order-data) in checkout UI extensions and Shopify Functions to implement custom validation for tax fields in checkout. You can apply checkout error targets to custom tax fields for precise error messages. We've added the [`HasLocalizedFields`](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/HasLocalizedFields) interface. We've also renamed the `localizationExtensions` field to `localizedFields` on the following types: * [`DraftOrderInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/DraftOrderInput#field-localizedfields) * [`input` argument on `OrderUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/orderUpdate#argument-input) ### Metafield admin access The `admin` field on the [`MetafieldAccessInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessInput#field-admin) and [`MetafieldAccessUpdateInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessUpdateInput#field-admin) objects is now optional. In API version 2024-10 and prior, this field was required. The `admin` field governs access to metafields. If you don't explicitly set the field, then the behavior works the same as if the field was omitted. Learn more about [metafield access controls](https://shopify.dev/docs/apps/build/custom-data/permissions). ### Metafield and metaobject permissions We're simplifying how metafield and metaobject permissions work to improve API response times. We've removed private and public permissions for [app-reserved metafields and metaobjects](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) from all mutations: * Removed `PRIVATE`, `PUBLIC_READ`, and `PUBLIC_READ_WRITE` values from app-reserved [metafield](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldAdminAccessInput) and [metaobject](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetaobjectAdminAccessInput) enums. * Removed the `LEGACY_LIQUID_ONLY` value from app-reserved [metafield](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldAdminAccess) and [metaobject](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetaobjectAdminAccess) enums. For more information on upcoming changes to metafields and metaobjects, refer to the [developer changelog](https://shopify.dev/changelog/simplifying-how-metafield-and-metaobject-permissions-work). ### Metafield definition capabilities We're sharing a consistent configuration pattern for capabilities between metafield and metaobject definitions, to unify and simplify how you enable optional features across custom data. To implement metafield definition capabilities, we've made the following changes: | Name | Type/field | Change | | - | - | - | | `useAsCollectionCondition` | Field | Removed. Use the `capabilities.smartCollectionCondition` field instead. For more information, refer to the [developer changelog](https://shopify.dev/changelog/metafield-definition-capability-framework-and-deprecation-of-use_as_collection_condition). | | `capabilities` | Field | Added to `standardMetafieldDefinitionEnable` mutation | | `capabilities` | Field | Added to `standardMetafieldDefinitionsEnable` mutation | | `INVALID_CAPABILITY` | Error code | Added to the `MetafieldDefinitionCreateUserErrorCode` and `MetafieldDefinitionUpdateUserErrorCode` enums. | | `TYPE_NOT_ALLOWED_FOR_CONDITIONS` | Error code | Added to the `MetafieldDefinitionCreateUserErrorCode` and `MetafieldDefinitionUpdateUserErrorCode` enums. | ### Metafield storefront visibility We've removed several `MetafieldStorefrontVisibility` related objects, mutations, queries, and fields: | Name | Type | Change | | - | - | - | | `MetafieldStorefrontVisibility` | Object | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `metafieldStorefrontVisibilityCreate` | Mutation | Removed. Use the `metafieldDefinitionUpdate` mutation instead. | | `metafieldStorefrontVisibilityDelete` | Mutation | Removed. Use the `metafieldDefinitionUpdate` mutation instead. | | `metafieldStorefrontVisibilities` | Query | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `metafieldStorefrontVisibility` | Query | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinition` object | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinitionInput` input object | Removed. Use the `access` field on the `MetafieldDefinitionInput` input object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinitionUpdateInput` input object | Removed. Use the `access` field on the `MetafieldDefinitionUpdateInput` input object instead. | ### Metafields remove private We've removed the [`PrivateMetafield`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/PrivateMetafield) from the public GraphQL Admin API, changing how `metafields` are implemented and used across stores. **Developer action required** * The [`PrivateMetafield`](https://shopify.dev/docs/api/admin-graphql/2024-10/queries/privateMetafield) was removed from the public GraphQL Admin API. Use [`app-data` metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#app-data-metafields) instead. * If the `metafield` is needed per resource, refer to the migration guide for using [`app-reserved` namespaces](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes). ### Multi-location shop feature We've removed the deprecated [`multiLocation`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/ShopFeatures#field-multilocation) field from the `ShopFeatures` object. Use the [`locationsCount`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/locationsCount) query instead to determine the number of shop locations. ### Payments bank account remove fields We've cleaned up the GraphQL Admin API `ShopifyPaymentsBankAccount` object and removed the following fields that weren't being used by third-party apps: * [`accountNumber`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/shopifypaymentsbankaccount#field-accountnumber) * [`routingNumber`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/shopifypaymentsbankaccount#field-routingnumber) ### Payment extensions [Payments extensions](https://shopify.dev/docs/apps/build/payments/credit-card/use-the-cli?framework=remix#create-a-payments-extension) that support vaulting have been improved to enable the processing of Three-Domain Secure (3DS) challenges for verifications. * A new mutation, [`VerificationSessionRedirect`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionRedirect), is introduced. * New arguments have been added to the existing [`VerificationSessionResolve`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionResolve) and [`VerificationSessionReject`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionReject) mutations. **Developer action required** For payments extensions that support vaulting, we strongly recommend that you update to the 2025-01 version as soon as possible. You also need to consider the following actions: * If 3DS is required for a verification, you must use the `VerificationSessionRedirect` mutation. * When resolving or rejecting a verification that required 3DS, pass the `authentication` argument to either the `VerificationSessionResolve` or `VerificationSessionReject` mutation. * We're also deprecating the following `VerificationSessionStateReason`: `REQUIRED_3DS_CHALLENGE`. Use the new `VerificationSessionRedirect` mutation instead. ### Price lists We've removed the following values on the [`PriceListUserErrorCode`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/PriceListUserErrorCode) enum that aren't currently returned by the GraphQL Admin API: * `CONTEXT_RULE_COUNTRIES_LIMIT` * `CONTEXT_RULE_COUNTRY_TAKEN` * `CONTEXT_RULE_LIMIT_REACHED` * `CONTEXT_RULE_MARKET_NOT_FOUND` * `CONTEXT_RULE_MARKET_TAKEN` * `COUNTRY_CURRENCY_MISMATCH` * `CURRENCY_COUNTRY_MISMATCH` * `MARKET_CURRENCY_MISMATCH` ### Product handle uniqueness validation The [`handle`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ProductInput#field-handle) field on the `ProductInput` input object is now validated for uniqueness. This enhancement ensures that there are no collisions when creating or updating product handles. The change doesn't affect existing behavior when a `handle` isn't provided as input. ### Product image deprecate We have changed the REST Admin API for the [product image resource](https://shopify.dev/docs/api/admin-rest/2024-10/resources/product-image) so that it returns a [`media image id`](https://shopify.dev/docs/api/storefront/2025-01/objects/MediaImage#field-id) instead of a product image GID. This is designed to make it easier to migrate to GraphQL from REST when interfacing with product images that were created before the introduction of a unified media ID. **Developer action required** Use `medias.id` instead of `medias.legacy_id`/`product_images.id` for the admin\_graphql\_api\_id. Previously, the `admin_graphql_api_id` returned a product image ID: `"gid://shopify/ProductImage/43701248884792"` Now, the `admin_graphql_api_id` returns a media image ID: `"gid://shopify/MediaImage/12379812379123"` This change will only affect clients using the latest 2025-01 API version. Older versions will continue to return the `ProductImage GID`, ensuring backward compatibility. It's strongly recommended that you upgrade to using GraphQL, as REST is nearing deprecation. ### Reverse fulfillment orders The [`order`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ReverseFulfillmentOrder#field-order) field on the `ReverseFulfillmentOrder` object is now nullable. An order can be nullable if the app meets any of the following conditions: * The app doesn't have the [`read_all_orders`](https://shopify.dev/docs/api/usage/access-scopes#orders-permissions) access scope. * The order is older than 60 days. * The order no longer exists. In API versions prior to 2025-01, the `order` field returns a GraphQL error when the order isn't available. ### Shop fields We've removed the following unused fields on the `Shop` object: * [`collectionSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-collectionsavedsearches). Use [`QueryRoot.collectionSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/collectionSavedSearches) instead. * [`draftOrderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-draftordersavedsearches). Use [`QueryRoot.draftOrderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/draftOrderSavedSearches) instead. * [`marketingEvents`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-marketingevents). Use [`QueryRoot.marketingEvents`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/marketingEvents) instead. * [`orderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-ordersavedsearches). Use [`QueryRoot.orderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/orderSavedSearches) instead. * [`productByHandle`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#field-productbyhandle). Use [`QueryRoot.productByHandle`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productByHandle) instead. * [`productSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-productsavedsearches). Use [`QueryRoot.productSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productSavedSearches) instead. * [`uploadedImagesByIds`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-uploadedimagesbyids). Use the [`files`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/files) query instead. ### Script tag display scopes We've reduced the available options for where a script is included when you create or update script tags. This change is related to the upcoming deprecation of script tags for the Thank you and Order status pages on August 28, 2025. [Learn more](https://shopify.dev/docs/apps/build/online-store/blocking-script-tags) about upcoming changes, key dates, and actions that you're required to take related to the deprecation of script tags. The only valid value for the [`displayScope`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ScriptTagInput#field-displayscope) field on the `ScriptTagInput` input object is now `ONLINE_STORE`. The `displayScope` field remains optional. When you omit this field from the [`scriptTagCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/scriptTagCreate) mutation, the value defaults to `ONLINE_STORE`. Review the following next steps based on how you currently use script tags: | If you use... | ...Then use this instead | | - | - | | UI customizations | Upgrade to [Shopify Extensions in Checkout](https://www.shopify.com/plus/upgrading-to-checkout-extensibility) | | Analytics and conversion tracking | Upgrade to [web pixels](https://shopify.dev/docs/apps/build/marketing-analytics/pixels) | | Online store | Update the `displayScope` value to `ONLINE_STORE` | *** ## Graph​QL Admin API changes Version 2025-01 of the GraphQL Admin API introduces the following changes: ### Add checkout branding customizations We've added the [customizations](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/CheckoutBrandingInput#field-customizations) fields, `merchandiseThumbnail.fit` and `merchandiseThumbnail.badge.background`, to the [`CheckoutBrandingInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/CheckoutBrandingInput#top) input object. You can now adjust the aspect ratio and image fit for product thumbnails, as well as the quantity badge background colors to align with your brand. ### Associating customers and orders We've added the [`OrderCreateUpsertCustomerAttributesInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/OrderCreateUpsertCustomerAttributesInput) input object that contains the input fields for creating a new customer object or for identifying an existing customer to update and associate with the order. We also added the `toUpsert` input field to the [`orderCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/orderCreate#argument-order) mutation, at `order.customer.toUpsert`. You can now create a new customer or update an existing customer when you create an order. ### Automatic discounts #### Breaking We've changed the [`minimumRequirement`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticBasic#field-minimumrequirement) field for both the [`DiscountAutomaticBasic`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticBasic) object and [`DiscountAutomaticFreeShipping`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticFreeShipping) object to be nullable. Previously, merchants were required to specify minimum purchase conditions on product, order, and free shipping automatic discounts. We're now making these conditions optional, so the [`minimumRequirement`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DiscountAutomaticFreeShipping#field-minimumrequirement) field can return a `null` value. ### Bulk query operations #### Breaking We've improved the [`BulkOperationUserError`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError) object by introducing a new [`code`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError#field-code) field for the `userErrors` returned by the [`bulkOperationRunQuery`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/bulkOperationRunQuery#field-bulkoperationrunquerypayload-usererrors) mutation. The new `code` field allows for improved error handling while retaining all the previous fields. We have also made the [`BulkOperationUserError`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BulkOperationUserError) type public, enabling developers to access this updated error information. ### Bundles grouped view We've added two new fields to represent product bundles, allowing you to accurately nest component products under the parent product in a grouped view. * The `[components](/docs/api/admin-graphql/2025-01/objects/AbandonedCheckoutLineItem#field-components)` field has been added to the `AbandonedCheckoutLineItem` object. Use this field to define the component products within a product bundle, ensuring a grouped view in Abandoned Checkout Emails. * The [`group`](https://shopify.dev/docs/api/customer/2025-01/objects/LineItem#field-group) field has been added to the \[`LineItem`] object. Use this field to indicate that line item products are a part of a product bundle, ensuring a grouped view in Orders Detail Pages. In addition, these fields can help you display product bundles in a grouped view in transactional emails, such as order confirmations and shipping updates. Learn how you can implement a grouped view by following [this tutorial](https://shopify.dev/docs/storefronts/themes/product-merchandising/bundles-emails). We've added the [customizations](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/CheckoutBrandingInput#field-customizations) fields, `merchandiseThumbnail.fit` and `merchandiseThumbnail.badge.background`, to the [`CheckoutBrandingInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/CheckoutBrandingInput#top) input object. You can now adjust the aspect ratio and image fit for product thumbnails, as well as the quantity badge background colors to align with your brand. ### Business entities We've added the [`BusinessEntity`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/BusinessEntity) object, which represents the formal and legal structure under which a merchant operates their business. You can use the [`businessEntities`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/businessEntities) query to retrieve information about business entities that are enabled on a merchant's shop. ### Combined listings The [`MISSING_OPTIONS_VALUE`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/CombinedListingUpdateUserErrorCode#value-missingoptionvalues) error code value has been added to the `CombinedListingUpdateUserErrorCode` enum. This error code is returned when the [`optionsAndValues`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/combinedListingUpdate#argument-optionsandvalues) field is empty. ### Company location tax settings We've added the [`taxExemptions`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/CompanyLocationTaxSettings#field-taxexemptions) and [`taxRegistrationId`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/CompanyLocationTaxSettings#field-taxregistrationid) fields on the `CompanyLocationTaxSettings` object. As a result, we've deprecated these fields from the root of the [`CompanyLocation`](https://shopify.dev/docs/api/functions/reference/order-routing-location-rule/graphql/common-objects/companylocation) object. Additionally, we've introduced a [`companyLocationTaxSettingsUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationTaxSettingsUpdate) mutation for updating [`tax_exempt`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationTaxSettingsUpdate#argument-taxexempt), [`taxExemptions`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/CompanyLocationTaxSettings#field-taxexemptions), and [`taxRegistrationId`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/CompanyLocationTaxSettings#field-taxregistrationid) for a company location. You should use this mutation in place of the following deprecated fields: * [`CompanyLocationAssignTaxExemptions`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationAssignTaxExemptions) * [`CompanyLocationCreateTaxRegistration`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationCreateTaxRegistration) * [`CompanyLocationRevokeTaxExemptions`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationRevokeTaxExemptions) * [`CompanyLocationRevokeTaxRegistration`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/companyLocationRevokeTaxRegistration) ### Conditional metafield definitions You can now use the [`metafieldDefinitionCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/metafieldDefinitionCreate) and [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/metafieldDefinitionUpdate) mutations to create and edit conditional metafield definitions. [Conditional metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/conditional-metafield-definitions) are definitions with constraints, which allow metafield definitions to be applied to a subset of resources. For example, each category metafield comes with a set of constraints that determine what product categories the metafield applies to. Currently, Shopify supports only product category constraints on product metafield definitions. To implement conditional metafield definitions, the following types and fields have been added: | Name | Type | Change | | | - | - | - | - | | `MetafieldDefinitionConstraintsInput` | Input object | Added | | | `MetafieldDefinitionConstraintsUpdatesInput` | Input object | Added | | | `constraints` | Field | Added to `MetafieldDefinitionInput` input object | | | `constraintsUpdates` | Field | Added to `MetafieldDefinitionUpdateInput` input object | | | `deleteConflictingConstrainedMetafields` | `deleteConflictingConstrainedMetafields` | Field | Added to `ProductUpdateInput` input object | | `linkedMetafieldValue` | Field | Added to `VariantOptionValueInput` input object | | | `INVALID_CONSTRAINTS` | Error code | Added to `MetafieldDefinitionCreateUserErrorCode` enum | | | `INVALID_CONSTRAINTS` | Error code | Added to `MetafieldDefinitionUpdateUserErrorCode` enum | | ### Custom ids We've added custom ID and upsert support to enhance data management across platforms. Use the custom ID support to assign unique identifiers to resources and look up the [resource by the custom ID](https://shopify.dev/docs/apps/build/custom-data/metafields/working-with-custom-ids#step-4-look-up-the-resource-by-the-custom-id). This simplifies the synchronization process and reduces data inconsistencies. Concurrently, you can use the upsert to either create or update a resource based on a matching key, reducing the number of API calls required. * **For custom IDs**: You can create and manage custom IDs for any data type that has metafield support. Refer to [metafieldDefinitionCreate](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/metafieldDefinitionCreate#field-metafielddefinitioncreatepayload-createddefinition) and [`identifier.customId`](https://shopify.dev/docs/api/admin-graphql/unstable/queries/productByIdentifier#argument-identifier) for details about defining the metafield definition `id` and the `key`, `namespace`, and `value` input fields used in creating a metafield ID. Note You can look up custom IDs only for products and customers. * **For upserts** - We've made two APIs available that allow upserting by a matching key. For products, use [`productSet`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/productSet) and for customers use [`customerSet`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/customerSet). You cannot yet use a custom ID as a matching key for upserting. Note Custom IDs and external keys are the same; external keys were renamed custom IDs. ### Customer payloads in webhook topics #### Breaking We've changed how a customer is represented in webhooks: * Removed the `tags` field. Use the [`CUSTOMER_TAGS_ADDED`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customertagsadded) and [`CUSTOMER_TAGS_REMOVED`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customertagsremoved) webhook topics instead. * Removed the `email_marketing_consent` field. Use the [`CUSTOMERS_EMAIL_MARKETING_CONSENT_UPDATE`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customersemailmarketingconsentupdate) webhook topic instead. * Removed the `sms_marketing_consent` field. Use the [`CUSTOMERS_MARKETING_CONSENT_UPDATE`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customersemailmarketingconsentupdate) webhook topic instead. * Removed the `last_order_id`, `last_order_name`, `total_spent`, and `orders_count` fields. Use the [`CUSTOMERS_PURCHASING_SUMMARY`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic#value-customerspurchasingsummary) webhook topic instead. The following [webhook topics](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/WebhookSubscriptionTopic) contain a customer payload: * `CHECKOUTS_CREATE` * `CHECKOUTS_UPDATE` * `CUSTOMERS_CREATE` * `CUSTOMERS_DELETE` * `CUSTOMERS_DISABLE` * `CUSTOMERS_ENABLE` * `CUSTOMERS_UPDATE` * `DRAFT_ORDERS_CREATE` * `DRAFT_ORDERS_UPDATE` * `ORDERS_CANCELLED` * `ORDERS_CREATE` * `ORDERS_FULFILLED` * `ORDERS_PAID` * `ORDERS_PARTIALLY_FULFILLED` * `ORDERS_UPDATED` ### Customer payment methods #### Breaking We've hidden the [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreditCardCreate) mutation, as it has been deprecated for more than three years. You can use the [`customerPaymentMethodRemoteCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreate) mutation instead to manage customer payment methods. Learn more about [payment processing](https://shopify.dev/docs/apps/build/payments/processing). **Developer action required** * We'll fully remove the [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreditCardCreate) mutation after January 2026, following the deprecation of the 2025-01 API version. You should transition away from using the [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreditCardCreate) mutation by January 2026. * The [`stripePaymentMethodId`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerpaymentmethodremotecreditcardcreate#argument-stripepaymentmethodid) argument, which is currently optional, is required in API version 2025-01. Update your code to accommodate this change in anticipation of the transition. Note The [`customerPaymentMethodRemoteCreditCardCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/customerPaymentMethodRemoteCreditCardCreate) mutation was primarily intended for creating payment methods using credit cards stored by Stripe. If the customer IDs you request are invalid, then the method returns a user error. ### Customer subscription contract order connection We've added a [`subscriptionContracts`](https://shopify.dev/docs/api/customer/2025-01/objects/Order#connection-subscriptioncontracts) connection to the `Order` object. This connection lets you query subscription contracts associated with a specific order, making it easier to manage customer subscriptions. ### Delivery promise settings We've added the [`DeliveryPromiseSetting`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/DeliveryPromiseSetting) object, which stores information about when customers can expect to receive their orders. With this addition you can do the following: * You can use the [`deliveryPromiseSettings`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/deliveryPromiseSettings) query to retrieve delivery promise settings for a shop. * You can make updates using the [`deliveryPromiseParticipantsUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/deliveryPromiseParticipantsUpdate) mutation. We’ve also added the [`delivery_promise_settings/update`](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-delivery_promise_settings/update) webhook topic so that your app can be notified when a delivery promise setting is updated. ### Discounts We've added the following new fields and error messages for managing discounts: | Name | Type | Change | | - | - | - | | `appliesOnOneTimeSubscription` | Field | Added to `DiscountAutomaticAppInput` input object | | `appliesOnOneTimePurchase` | Field | Added to `DiscountAutomaticApp` input object | | `appliesOnOneTimePurchase` | Field | Added to `DiscountCodeApp` object | | `appliesOnOneTimePurchase` | Field | Added to `DiscountCodeAppInput` input object | | `appliesOnSubscription` | Field | Added to `DiscountCodeAppInput` input object | | `appliesOnSubscription` | Field | Added to `DiscountCodeApp` object | | `APPLIES_ON_ONE_TIME_PURCHASE_AND_SUBSCRIPTION_BOTH_FALSE` | Error code | Added to `DiscountErrorCode` enum | | `MULTIPLE_RECURRING_CYCLE_LIMIT_FOR_NON_SUBSCRIPTION_ITEMS_CONSTRAINTS` | Error code | Added to `DiscountErrorCode` enum | | `recurringCycleLimit` | Field | Added to `DiscountCodeAppInput` input object | | `RECURRING_CYCLE_LIMIT_NOT_A_VALID_INTEGER` | Error code | Added to `PriceRuleErrorCode` enum | | `RECURRING_CYCLE_LIMIT_NOT_A_VALID_INTEGER` | Error code | Added to `DiscountErrorCode` enum | ### Discount code filter added We've added a new [`code`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/discountNodes#argument-query-filter-code) filter parameter to the `discountNodes` query, allowing you to filter discounts by their associated discount codes. Note Filtering by the discount code is not supported for bulk discounts. ### Draft order overrides We've added the [`priceOverride`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/DraftOrderLineItemInput#field-priceoverride) field on the [`DraftOrderLineItemInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/DraftOrderLineItemInput#top) input object. This latest enhancement enables you to use the field to customize pricing at the draft order level. You can specify a price override for the line item, which will replace the product variant's catalog price for that draft order. This functionality allows for greater flexibility in managing pricing directly at the draft order level: * Use the [`priceOverride`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/DraftOrderLineItemInput#field-priceoverride) field to customize pricing at the draft order level. * Specify a price override for the line item, which will replace the product variant's catalog price for that draft order. You need to handle currency conversion and understand the restrictions concerning [`bundles`](https://shopify.dev/docs/apps/build/product-merchandising/bundles). Price overrides cannot be applied to [`bundles`](https://shopify.dev/docs/apps/build/product-merchandising/bundles) or their components. If a line item is included in a `bundle`, any price override will be removed. ### Error codes for cart submission We've added new error codes to the [`SubmissionErrorCode`](https://shopify.dev/docs/api/storefront/2025-01/enums/SubmissionErrorCode) enum. These enhancements provide clearer feedback when issues occur during the cart submission process. The new error codes enhance the detail and clarity of error responses when cart submission fails. ### Exchanges We've added the [`variantId`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/CalculateExchangeLineItemInput#field-variantid) field to the `CalculateExchangeLineItemInput` input object. You can use this field to set the ID of the product variant to be added to the order as part of an exchange. ### Fulfillment hold access #### Breaking We've introduced validation for fulfillment hold access in node queries. This change only affects apps which fetch fulfillment holds using a [`node` or `nodes` GraphQL query](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#interface-node). If your app doesn't currently have sufficient access scopes as defined below then you need to request the correct access scopes before migrating to the 2025-01 API version. When using a `node` or `nodes` query to fetch holds, if your app doesn't have sufficient access, then a `null` value is returned for any fulfillment holds that you don't have access to. Refer to the API access scopes section of the [`FulfillmentOrder`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentOrder) object for more information about access scopes. **Developer action required** Apps using the `node` or `nodes` GraphQL queries to fetch fulfillment holds will only retrieve those associated with fulfillment orders for which they have access: | Access scope | What you can access | | - | - | | `read_merchant_managed_fulfillment_orders` | Holds on fulfillment orders assigned to a merchant-managed location | | `read_assigned_fulfillment_orders` | Holds on fulfillment orders assigned to locations owned by your app | | `read_third_party_fulfillment_orders` | Holds on fulfillment orders assigned to a third-party location | | `read_marketplace_fulfillment_orders` | Holds on fulfillment orders that belong to one of your marketplace's orders | ### Fulfillment hold field replacement #### Breaking We've added the new [`heldByApp`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#field-heldbyapp) object field on the [FulfillmentHold](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#top) object, replacing the [`heldBy`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/FulfillmentHold#field-heldby) string field. **Developer action required** The `heldByApp` object field provides access to all attributes of the App object, in contrast to the deprecated `heldBy` field, which only indicated the app's title. If you currently query `fulfillmentHold.heldBy`, you should transition to querying `fulfillmentHold.heldByApp.title`. For more information, refer to the [changelog](https://shopify.dev/changelog/update-to-fulfillmenthold-heldbyapp-field-from-fulfillmenthold-heldby-field). ### Fulfillment holds #### Breaking You can now place multiple holds on a fulfillment order. Each hold captures a specific issue independently, allowing you to release holds individually while maintaining other active holds. For detailed information on the changes, and how to upgrade to the 2025-01 version of the GraphQL Admin API, consult the [developer changelog](https://shopify.dev/changelog/apply-multiple-holds-to-a-single-fulfillment-order). ### Fulfillment services #### Breaking The default value of the [`permitsSkuSharing`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentService#field-permitsskusharing) field on the [`fulfillmentServiceCreate` mutation](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentService#top) is now `true`. If `permitsSkuSharing` is `true`, then a fulfillment service can stock inventory at multiple fulfillment services or merchant-managed locations. ### Localization extension keys We've added the [`SHIPPING_CREDENTIAL_MX`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/LocalizationExtensionKey#value-shippingcredentialmx) extension key to the `LocalizationExtensionKey` enum. Use this extension key to retrieve the shipping credentials for cross-border shipments to Mexico. ### Localized fields #### Breaking You can now use [localized fields](https://shopify.dev/docs/apps/build/markets/add-locally-required-order-data) in checkout UI extensions and Shopify Functions to implement custom validation for tax fields in checkout. You can apply checkout error targets to custom tax fields for precise error messages. We've added the [`HasLocalizedFields`](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/HasLocalizedFields) interface. We've also renamed the `localizationExtensions` field to `localizedFields` on the following types: * [`DraftOrderInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/DraftOrderInput#field-localizedfields) * [`input` argument on `OrderUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/orderUpdate#argument-input) ### Location query id We've added the [`location_id`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/locations#argument-query-filter-location_id) filter to the `locations` query. The location ID allows you to specify the location where the physical good resides. If no ID is specified, then the primary location is used. ### Manual payment gateway We’ve added the [`manualPaymentGateway`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/OrderTransaction#field-manualpaymentgateway) field to the `OrderTransaction` object. The `manualPaymentGateway` field indicates whether the transaction is processed by a manual payment gateway. For more information about manual payments, refer to [Manual payment methods](https://help.shopify.com/manual/payments/manual-payments). ### Metafield admin access #### Breaking The `admin` field on the [`MetafieldAccessInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessInput#field-admin) and [`MetafieldAccessUpdateInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldAccessUpdateInput#field-admin) objects is now optional. In API version 2024-10 and prior, this field was required. The `admin` field governs access to metafields. If the field isn't explicitly set, then the behavior works the same as if the field was omitted. Learn more about [metafield access controls](https://shopify.dev/docs/apps/build/custom-data/permissions). ### Metafields input query variables [Metafields input query](https://shopify.dev/docs/apps/build/functions/input-queries/metafields-for-input-queries) variables are now subject to additional validation across all Function APIs. Previously, if these metafields didn't contain properly formatted data, we treated them as empty. This could lead to situations where it was difficult to determine why a function wasn't receiving the expected input data. Now, an invalid metafield will result in an `InvalidVariableValueError` when attempting to run the function. For more information, refer to the [list of errors](https://shopify.dev/docs/apps/build/functions/monitoring-and-errors#list-of-errors). --> ### Metafields remove private #### Breaking We've removed the [`PrivateMetafield`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/PrivateMetafield) from the public GraphQL Admin API, changing how `metafields` are implemented and used across stores. **Developer action required** * The [`PrivateMetafield`](https://shopify.dev/docs/api/admin-graphql/2024-10/queries/privateMetafield) was removed from the public GraphQL Admin API. Use [`app-data` metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#app-data-metafields) instead. * If the `metafield` is needed per resource, refer to the migration guide for using [`app-reserved` namespaces](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes). ### Metafield and metaobject permissions #### Breaking We're simplifying how metafield and metaobject permissions work to improve API response times. We've removed private and public permissions for [app-reserved metafields and metaobjects](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) from all mutations: * Removed `PRIVATE`, `PUBLIC_READ`, and `PUBLIC_READ_WRITE` values from app-reserved [metafield](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldAdminAccessInput) and [metaobject](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetaobjectAdminAccessInput) enums. * Removed the `LEGACY_LIQUID_ONLY` value from app-reserved [metafield](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldAdminAccess) and [metaobject](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetaobjectAdminAccess) enums. For more information on upcoming changes to metafields and metaobjects, refer to the [developer changelog](https://shopify.dev/changelog/simplifying-how-metafield-and-metaobject-permissions-work). ### Metafield definition capabilities #### Breaking We're sharing a consistent configuration pattern for capabilities between metafield and metaobject definitions, to unify and simplify how you work with custom data. | Name | Type/field | Change | | - | - | - | | `useAsCollectionCondition` | Field | Removed. Use the `capabilities.smartCollectionCondition` field instead. For more information, refer to the [developer changelog](https://shopify.dev/changelog/metafield-definition-capability-framework-and-deprecation-of-use_as_collection_condition). | | `capabilities` | Field | Added to `standardMetafieldDefinitionEnable` mutation | | `capabilities` | Field | Added to `standardMetafieldDefinitionsEnable` mutation | | `INVALID_CAPABILITY` | Error code | Added to the `MetafieldDefinitionCreateUserErrorCode` and `MetafieldDefinitionUpdateUserErrorCode` enums. | | `TYPE_NOT_ALLOWED_FOR_CONDITIONS` | Error code | Added to the `MetafieldDefinitionCreateUserErrorCode` and `MetafieldDefinitionUpdateUserErrorCode` enums. | ### Metafield definition uniqueness You can now use the [`MetafieldCapabilityUniqueValues`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldCapabilityUniqueValues) object and [`MetafieldCapabilityUniqueValuesInput`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/MetafieldCapabilityUniqueValuesInput) input object to retrieve metafield definitions that enforce uniqueness. You can use this capability to ensure that each metafield has a unique value across all resources. Currently, you can only enforce uniqueness on metafield definitions that don’t yet have associated metafields. You can enforce uniqueness for the following [data types](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-data-types#supported-types): * `single_line_text_field` * `number_integer` * `url` * `id` ### New metafields​Delete mutation #### Breaking We've removed the [`metafieldDelete`](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDelete) mutation and replaced it with the [`metafieldsDelete`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/metafieldsDelete) mutation. The former mutation relies on the `Metafield` group identifier (`gid`), while the latter takes an array of [`MetafieldIdentifier`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldIdentifier#top) fields composed of [`key`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldIdentifier#field-key), [`namespace`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldIdentifier#field-namespace), and [`ownerId`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/MetafieldIdentifier#field-ownerid). Note The metafield `gid` isn't an option in the `metafieldsDelete` mutation. ### Metafield storefront visibility #### Breaking We've removed several `MetafieldStorefrontVisibility`-related objects, mutations, queries, and fields: | Name | Type | Change | | - | - | - | | `MetafieldStorefrontVisibility` | Object | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `metafieldStorefrontVisibilityCreate` | Mutation | Removed. Use the `metafieldDefinitionUpdate` mutation instead. | | `metafieldStorefrontVisibilityDelete` | Mutation | Removed. Use the `metafieldDefinitionUpdate` mutation instead. | | `metafieldStorefrontVisibilities` | Query | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `metafieldStorefrontVisibility` | Query | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinition` object | Removed. Use the `access` field on the `MetafieldDefinition` object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinitionInput` input object | Removed. Use the `access` field on the `MetafieldDefinitionInput` input object instead. | | `visibleToStorefrontApi` | Field on `MetafieldDefinitionUpdateInput` input object | Removed. Use the `access` field on the `MetafieldDefinitionUpdateInput` input object instead. | ### Multi-location shop feature #### Breaking We've removed the deprecated [`multiLocation`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/ShopFeatures#field-multilocation) field from the `ShopFeatures` object. Use the [`locationsCount`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/locationsCount) query instead to determine the number of shop locations. ### Orders webhook includes product bundles information We've added the `sales_line_item_group_id` field to the [`orders/create`](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-orders/create) webhook. This field allows you to determine if a specific `line_item` is part of a [product bundle](https://shopify.dev/docs/apps/build/product-merchandising/bundles). When a `line_item` belongs to a product bundle, it will have an associated `sales_line_item_group_id`. ### Pickup address You can now use the `pickupAddress` field in both the [`SubscriptionDeliveryMethodPickupOption`](https://shopify.dev/docs/api/customer/2025-01/objects/SubscriptionDeliveryMethodPickupOption#field-pickupaddress) and [`SubscriptionPickupOption`](https://shopify.dev/docs/api/customer/2025-01/objects/SubscriptionPickupOption) objects to query for a customer pickup address. ### Price lists #### Breaking We've removed the following values on the [`PriceListUserErrorCode`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/PriceListUserErrorCode) enum that aren't currently returned by the GraphQL Admin API: * `CONTEXT_RULE_COUNTRIES_LIMIT` * `CONTEXT_RULE_COUNTRY_TAKEN` * `CONTEXT_RULE_LIMIT_REACHED` * `CONTEXT_RULE_MARKET_NOT_FOUND` * `CONTEXT_RULE_MARKET_TAKEN` * `COUNTRY_CURRENCY_MISMATCH` * `CURRENCY_COUNTRY_MISMATCH` * `MARKET_CURRENCY_MISMATCH` ### Product handle uniqueness validation #### Breaking The [`handle`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ProductInput#field-handle) field on the `ProductInput` input object is now validated for uniqueness. This enhancement ensures that there are no collisions when creating or updating product handles. The change doesn't affect existing behavior when a handle isn't provided as input. ### Product metadata queries We've moved the following product metadata queries from the [`Shop`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop) type to `QueryRoot` and added pagination support: | Name | Type | Change | | - | - | - | | `productTags` | Query | Moved to `QueryRoot` with pagination support | | `productTypes` | Query | Moved to `QueryRoot` with pagination support | | `productVendors` | Query | Moved to `QueryRoot` with pagination support | Previously, these fields were available on the [`Shop`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop) type with a limit of 250 results. The new implementation removes this limitation and supports pagination through standard cursor-based connections. ### Reverse fulfillment orders #### Breaking The [`order`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ReverseFulfillmentOrder#field-order) field on the `ReverseFulfillmentOrder` object is now nullable. An order can be nullable if the app meets any of the following conditions: * The app doesn't have the [`read_all_orders`](https://shopify.dev/docs/api/usage/access-scopes#orders-permissions) access scope. * The order is older than 60 days. * The order no longer exists. In API versions prior to 2025-01, the `order` field returns a GraphQL error when the order isn't available. ### Revocation reasons for payment methods We've added the `PAYMENT_METHOD_VERIFICATION_FAILED` and `THREE_D_SECURE_FLOW_IN_VERIFICATION_NOT_IMPLEMENTED` values to the [`CustomerPaymentMethodRevocationReason`](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/CustomerPaymentMethodRevocationReason) enum to provide more granular information about payment method revocations. This enhancement helps apps handle scenarios where a customer's payment method needs to be revoked. ### Shopify Payments bank account fields removed #### Breaking We've removed the following fields from the `ShopifyPaymentsBankAccount` object that weren't being used by third-party apps: * [`accountNumber`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/shopifypaymentsbankaccount#field-accountnumber) * [`routingNumber`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/shopifypaymentsbankaccount#field-routingnumber) ### Script tag display scopes #### Breaking We've reduced the available options for where a script is included when you create or update script tags. This change is related to the upcoming deprecation of script tags for the Thank you and Order status pages on August 28, 2025. [Learn more](https://shopify.dev/docs/apps/build/online-store/blocking-script-tags) about upcoming changes, key dates, and actions that you're required to take related to the deprecation of script tags. The only valid value for the [`displayScope`](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ScriptTagInput#field-displayscope) field on the `ScriptTagInput` input object is now `ONLINE_STORE`. The `displayScope` field remains optional. When you omit this field from the [`scriptTagCreate`](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/scriptTagCreate) mutation, the value defaults to `ONLINE_STORE`. | If you use... | ...Then use this instead | | - | - | | UI customizations | Upgrade to [Shopify Extensions in Checkout](https://www.shopify.com/plus/upgrading-to-checkout-extensibility) | | Analytics and conversion tracking | Upgrade to [web pixels](https://shopify.dev/docs/apps/build/marketing-analytics/pixels) | | Online store | Update the `displayScope` value to `ONLINE_STORE` | ### Shop fields #### Breaking We've removed the following unused fields on the `Shop` object: * [`collectionSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-collectionsavedsearches). Use [`QueryRoot.collectionSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/collectionSavedSearches) instead. * [`draftOrderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-draftordersavedsearches). Use [`QueryRoot.draftOrderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/draftOrderSavedSearches) instead. * [`marketingEvents`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-marketingevents). Use [`QueryRoot.marketingEvents`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/marketingEvents) instead. * [`orderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-ordersavedsearches). Use [`QueryRoot.orderSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/orderSavedSearches) instead. * [`productByHandle`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#field-productbyhandle). Use [`QueryRoot.productByHandle`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productByHandle) instead. * [`productSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-productsavedsearches). Use [`QueryRoot.productSavedSearches`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productSavedSearches) instead. * [`uploadedImagesByIds`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop#connection-uploadedimagesbyids). Use the [`files`](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/files) query instead. ### Shopify Payments accounts We've added the [`accountOpenerName`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ShopifyPaymentsAccount#field-accountopenername) field to the `ShopifyPaymentsAccount` object. You can use the field to query the name of the person that opened the Shopify Payments account. ### Single product variant connection You can use a limit of up to 2000 variants when running a query on a single product, such as [`product`](https://shopify.dev/docs/api/storefront/2025-01/queries/product) or [`productByHandle`](https://shopify.dev/docs/api/storefront/2025-01/queries/productByHandle). This enhanced limit doesn't apply if you make multiple queries in one request, or are accessing the variants any other way except through the [`ProductVariantConnection`](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ProductVariantConnection#field-product-variants). ### String connection nodes The `StringConnection` connection now includes a [`nodes`](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/StringConnection#field-stringconnection-nodes) field, which provides a list of strings within the connection. The `nodes` field contains a list of nodes contained in [`StringEdge`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/StringEdge). This `StringEdge` contains one `String` and a cursor. The `StringConnection` and its associated `Edge` are cacheable, for improved performance. This addition makes it easier for developers to access the individual elements in a string connection seamlessly. ### Subscription contracts We’ve introduced the [`concatenatedOriginContract`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/SubscriptionLine#field-concatenatedorigincontract) field to the `SubscriptionLine` object. The `concatenatedOriginContract` field provides information about the originating contract of the subscription line, and specifically whether it was created by concatenating multiple contracts. The `concatenatedOriginContract` field returns an instance of [`SubscriptionContract`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/SubscriptionContract), which can be `null` if no concatenation is present. ### Product metadata queries We've moved the following product metadata queries from the [`Shop`](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/Shop) type to `QueryRoot` and added pagination support: | Name | Type | Change | | - | - | - | | `productTags` | Query | Moved to `QueryRoot` with pagination support | | `productTypes` | Query | Moved to `QueryRoot` with pagination support | | `productVendors` | Query | Moved to `QueryRoot` with pagination support | We’ve introduced the [`concatenatedOriginContract`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/SubscriptionLine#field-concatenatedorigincontract) field to the `SubscriptionLine` object. The `concatenatedOriginContract` field provides information about the originating contract of the subscription line, and specifically whether it was created by concatenating multiple contracts. The `concatenatedOriginContract` field returns an instance of [`SubscriptionContract`](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/SubscriptionContract), which can be `null` if no concatenation is present. *** ## Shopify Function APIs changes Version 2025-01 of the Shopify Function APIs introduces the following changes: ### Header selection field We've added the `header` field to the [`HttpResponse`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql/common-objects/httpresponse) object. This field allows you to query for a specific HTTP header and add a specific header field to the function's external calls response. The `header` field is available across all [Shopify Function APIs](https://shopify.dev/docs/api/functions). The new `header` field includes a required `name` argument. This argument lets you specify a case-insensitive header name to retrieve its value. With this header field, you can access individual HTTP headers on demand. This provides more granular control compared to the previously available `headers` field, which returned all headers as a list. The `header` field returns an instance of the [`HttpResponseHeader`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql/common-objects/httpresponseheader) type. Caution The replaced `headers` field remains available but is deprecated. We recommend that you use the 'header' field instead. ### JSON body support We now provide native support of a HTTP request body as a `JSON_body` for function external calls. Use this field when the `body` is in JSON format to reduce function instruction consumption and to ensure the `body` is formatted in logs. Don't use the `JSON_body` field together with the `body` field in the [`HttpResponse`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql/common-objects/httpresponse) object. If both are provided, then the `HttpResponse`'s `body` field takes precedence. If the `JSON_body` field is specified and no `Content-Type` header is included, then the header will automatically be set to `application/json`. ### Localized fields for cart and checkout validation We've added the [`paymentDetails`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionResolve#argument-paymentdetails) field on the `verificationSessionResolve` mutation. This field allows payment providers to send payment details as arguments to a `card` input field, such as `billingAddress` and `cardHolderName`. *** ## Payments Apps API changes Version 2025-01 of the Payments Apps API introduces the following changes: ### Localized fields for cart and checkout validation We've added a `localizedFields` attribute to the [`Cart`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql/common-objects/cart) object for function inputs. This attribute returns the localized fields available for the cart. Values are only returned for server-side validations using the [`purchase.validation.run`](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql#extension-targets) extension target. ### Payment extensions #### Breaking [Payments extensions](https://shopify.dev/docs/apps/build/payments/credit-card/use-the-cli?framework=remix#create-a-payments-extension) that support vaulting have been improved to enable the processing of Three-Domain Secure (3DS) challenges for verifications. * A new mutation, [`VerificationSessionRedirect`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionRedirect), is introduced. * New arguments have been added to the existing [`VerificationSessionResolve`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionResolve) and [`VerificationSessionReject`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionReject) mutations. **Developer action required** For payments extensions that support vaulting, we strongly recommend that you update to the 2025-01 version as soon as possible. You also need to consider the following actions: * If 3DS is required for a verification, you must use the `VerificationSessionRedirect` mutation. * When resolving or rejecting a verification that required 3DS, pass the `authentication` argument to either the `VerificationSessionResolve` or `VerificationSessionReject` mutation. * We're also deprecating the following `VerificationSessionStateReason`: `REQUIRED_3DS_CHALLENGE`. Use the new `VerificationSessionRedirect` mutation instead. ### Product image resource #### Breaking We have changed the [product image resource](https://shopify.dev/docs/api/admin-rest/2024-10/resources/product-image) so that it returns a media ID instead of a product image GID. This is designed to make it easier to migrate to GraphQL from REST when interfacing with product images that were created before the introduction of a unified media ID. **Developer action required** Use `medias.id` instead of `medias.legacy_id`/`product_images.id` for the admin\_graphql\_api\_id. * Previously, the `admin_graphql_api_id` returned a product image ID: `"gid://shopify/ProductImage/43701248884792"` * Now, the `admin_graphql_api_id` returns a media image ID: `"gid://shopify/MediaImage/12379812379123"` This change will only affect clients using the latest 2025-01 API version. Older versions will continue to return the `ProductImage GID`, ensuring backward compatibility. It's strongly recommended that you upgrade to using GraphQL, as REST is nearing deprecation. ### Verification session payment details We've added the [`paymentDetails`](https://shopify.dev/docs/api/payments-apps/2025-01/mutations/verificationSessionResolve#argument-paymentdetails) field on the `verificationSessionResolve` mutation. This field allows payment providers to send payment details as arguments to its `paymentDetails.card` input field. *** ## Storefront API changes Version 2025-01 of the Storefront API introduces the following changes: ### Cart delivery addresses We've added an [`addresses`](https://shopify.dev/docs/api/storefront/2025-01/objects/CartDelivery#field-addresses) field to the `CartDelivery` object. This field returns a list of addresses that customers can select for their cart delivery, providing more flexible shipping options. ### Cart tax and duties deprecated We've deprecated the following tax and duty fields on the `Cart` object's [`cost`](https://shopify.dev/docs/api/storefront/2025-01/objects/Cart#field-cost) field: * `totalDutyAmount` * `totalDutyAmountEstimated` * `totalTaxAmount` * `totalTaxAmountEstimated` Tax and duties are now calculated at checkout within the complete context of the customer's information, ensuring greater accuracy. ### String connection nodes The [`StringConnection`](https://shopify.dev/docs/api/storefront/2025-01/connections/StringConnection) connection now includes a [`nodes`](https://shopify.dev/docs/api/storefront/2025-01/connections/StringConnection#field-stringconnection-nodes) field, which provides a list of strings within the connection. The `nodes` field contains a list of nodes contained in [`StringEdge`](https://shopify.dev/docs/api/storefront/2025-01/objects/StringEdge). This `StringEdge` contains one `String` and a cursor. The `StringConnection` and its associated `Edge` are cacheable, for improved performance. This addition makes it easier for developers to access the individual elements in a string connection. *** ## REST Admin API changes Version 2025-01 of the REST Admin API introduces the following changes: ### Business entities We've added business entity identifiers on the [Order](https://shopify.dev/docs/api/admin-rest/2025-01/resources/order) resource, as well as on webhook payloads. These identifiers represents the formal and legal structure under which a merchant operates their business. *** * [Highlights](https://shopify.dev/docs/api/release-notes/2025-01.md#highlights) * [Breaking changes](https://shopify.dev/docs/api/release-notes/2025-01.md#breaking-changes) * [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#graphql-admin-api-changes) * [Shopify Function APIs changes](https://shopify.dev/docs/api/release-notes/2025-01.md#shopify-function-apis-changes) * [Payments Apps API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#payments-apps-api-changes) * [Storefront API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#storefront-api-changes) * [REST Admin API changes](https://shopify.dev/docs/api/release-notes/2025-01.md#rest-admin-api-changes)