2025-01 release notes (release candidate)
| Release date | Date version is no longer supported |
|---|---|
| January 1, 2025 | January 1, 2026 |
The 2025-01 version of Shopify's APIs include the following highlights:
Automatic discounts: The
minimumRequirementfield for both theDiscountAutomaticBasicandDiscountAutomaticFreeShippingobjects is now nullable, making minimum purchase conditions optional for automatic discounts.Bulk query operations: The
BulkOperationUserErrorobject has been updated with a newUserErrorGraphQL object type, which includes an additionalcodefield.Fulfillment services: The default value for the
permitsSkuSharingfield on thefulfillmentServiceCreatemutation is now set totrue, 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_bodyfor function external calls. Use this field when thebodyis in JSON format to reduce function instruction consumption and to ensure thebodyis formatted in logs. Don't use theJSON_bodyfield together with thebodyfield in theHttpResponseobject. If both are provided, then theHttpResponse'sbodyfield takes precedence. If theJSON_bodyfield is specified and noContent-Typeheader is included, then the header will automatically be set toapplication/json.Metafield admin access: The
adminfield on theMetafieldAccessInputandMetafieldAccessUpdateInputobjects 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
accessfield on theMetafieldDefinitionobject instead.Multi-location shop feature: The deprecated
multiLocationfield has been removed from theShopFeaturesobject. Use thelocationsCountquery to determine the number of shop locations.New metafieldsDelete mutation: We've replaced the
metafieldDeletemutation with themetafieldsDeletemutation. This change provides a fundamental update in how you delete metafields. By usingmetafieldsDelete, you need to adjust your code to accommodate for a new identifier format.Product handle uniqueness validation: The
handlefield on theProductInputinput object is now validated for uniqueness, preventing collisions when creating or updating product handles.
Breaking changes
Anchor link to section titled "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
Anchor link to section titled "Automatic discounts"We've changed the minimumRequirement field for both the DiscountAutomaticBasic object and 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 field can return a null value.
Bulk query operations
Anchor link to section titled "Bulk query operations"In the Admin API, we have improved the BulkOperationUserError object by introducing a new code field for the userErrors returned by the bulkOperationRunQuery mutation. The new code field allows for improved error handling while retaining all the previous fields. We have also made the BulkOperationUserError type public, enabling developers to access this updated error information.
Fulfillment servicesg
Anchor link to section titled "Fulfillment servicesg"The default value of the permitsSkuSharing field on the fulfillmentServiceCreate mutation is now true. If permitsSkuSharing is true, then a fulfillment service can stock inventory at multiple fulfillment services or merchant-managed locations.
Metafield admin access
Anchor link to section titled "Metafield admin access"The admin field on the MetafieldAccessInput and MetafieldAccessUpdateInput objects is now optional. In API version 2024-10 and prior, this field was required.
The admin field governs access to metafields. If the field isn't explicitly set, then the behavior works the same as if the field was omitted.
Learn more about metafield access controls.
Metafield storefront visibility
Anchor link to section titled "Metafield storefront visibility"We've removed several MetafieldStorefrontVisibility related objects, mutations, queries, and fields:
| Name | Type | Change |
|---|---|---|
MetafieldStorefrontVisibility |
Object | Removed. Use the access field on the MetafieldDefinition object instead. |
metafieldStorefrontVisibilityCreate |
Mutation | Removed. Use the metafieldDefinitionUpdate mutation instead. |
metafieldStorefrontVisibilityDelete |
Mutation | Removed. Use the metafieldDefinitionUpdate mutation instead. |
metafieldStorefrontVisibilities |
Query | Removed. Use the access field on the MetafieldDefinition object instead. |
metafieldStorefrontVisibility |
Query | Removed. Use the access field on the MetafieldDefinition object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinition object |
Removed. Use the access field on the MetafieldDefinition object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinitionInput input object |
Removed. Use the access field on the MetafieldDefinitionInput input object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinitionUpdateInput input object |
Removed. Use the access field on the MetafieldDefinitionUpdateInput input object instead. |
Multi-location shop feature
Anchor link to section titled "Multi-location shop feature"We've removed the deprecated multiLocation field from the ShopFeatures object.
Product handle uniqueness validation
Anchor link to section titled "Product handle uniqueness validation"The 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.
GraphQL Admin API changes
Anchor link to section titled "GraphQL Admin API changes"The following changes are introduced in the 2025-01 version of the GraphQL Admin API.
Automatic discounts
We've changed the minimumRequirement field for both the DiscountAutomaticBasic object and 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 field can return a null value.
Bulk query operations
In the Admin API, we have introduced UserError as a new GraphQL object type to the BulkOperationUserError object. The new object type includes an additional code field and retains the same fields as the old type.
Combined listings
The MISSING_OPTIONS_VALUE error code value has been added to the CombinedListingUpdateUserErrorCode enum. This error code is returned when the optionsAndValues field is empty.
Exchanges
We've added the variantId field to the CalculateExchangeLineItemInput input object. You can use this field to set the ID of the product variant to be added to the order as part of an exchange.
Fulfillment services
The default value for the permitsSkuSharing field on the fulfillmentServiceCreate mutation is now set to true, allowing fulfillment services to stock inventory across multiple locations.
Metafield admin access
The admin field on the MetafieldAccessInput and MetafieldAccessUpdateInput objects is now optional. In API version 2024-10 and prior, this field was required.
The admin field governs access to metafields. If the field isn't explicitly set, then the behavior works the same as if the field was omitted.
Learn more about metafield access controls.
New metafieldsDelete mutation
We've removed the metafieldDelete mutation and replaced it with the metafieldsDelete mutation. The former mutation relies on the Metafield group identifier (gid), while the latter takes an array of MetafieldIdentifier fields composed of key, namespace, and ownerId.
Metafield storefront visibility
We've removed several MetafieldStorefrontVisibility-related objects, mutations, queries, and fields:
| Name | Type | Change |
|---|---|---|
MetafieldStorefrontVisibility |
Object | Removed. Use the access field on the MetafieldDefinition object instead. |
metafieldStorefrontVisibilityCreate |
Mutation | Removed. Use the metafieldDefinitionUpdate mutation instead. |
metafieldStorefrontVisibilityDelete |
Mutation | Removed. Use the metafieldDefinitionUpdate mutation instead. |
metafieldStorefrontVisibilities |
Query | Removed. Use the access field on the MetafieldDefinition object instead. |
metafieldStorefrontVisibility |
Query | Removed. Use the access field on the MetafieldDefinition object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinition object |
Removed. Use the access field on the MetafieldDefinition object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinitionInput input object |
Removed. Use the access field on the MetafieldDefinitionInput input object instead. |
visibleToStorefrontApi |
Field on MetafieldDefinitionUpdateInput input object |
Removed. Use the access field on the MetafieldDefinitionUpdateInput input object instead. |
Multi-location shop feature
We've removed the deprecated multiLocation field from the ShopFeatures object. Use the locationsCount query instead to determine the number of shop locations.
New orderCreate field
We've added a new input field, toUpsert, to the orderCreate mutation. This field allows for the upsertion of customers during the order creation process, facilitating the specification of either a new or existing customer. The toUpsert input field is located on the orderCreate reference page under the Arguments > order > customer > input fields headings. This change enhances the flexibility of the order creation workflow.
Product handle uniqueness validation
The 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.
Shopify Function APIs changes
Anchor link to section titled "Shopify Function APIs changes"The following changes are introduced in the 2025-01 version of Shopify Function APIs.
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 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.