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