2023-10 release notes

What's new in 2023-10

The following features were added in version 2023-10 of Shopify's APIs:

Highlights from the GraphQL and REST Admin API changes:

• We've added the compareAtPriceRange field to Product, which returns the minimum and maximum compare-at prices across a product's variants

• You can now identify the variant that was used to model a bundle after it was purchased by querying the productvariantid field of LineItemGroup.

• We've added STAFF to the OrderCancelReason GraphQL type, as a reason for canceling orders due to staff error.

• Apps can now change the name and address of fulfillment service locations.

• More flexible primary markets for multi-country stores

• We've added a cancellation field to the GraphQL Admin API's Order object. Query this field for more details about an order's cancelation, such as any staff-provided notes on why the order was cancelled on a POS app.

  Highlights from the Storefront API changes:

• Cart line items are now ordered in reverse chronological order based on when they were added.

Anchor to Breaking changesBreaking 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.

Anchor to More flexible primary marketsMore flexible primary markets

As of API version 2023-10, primary markets can be customized in three new ways:

• Transactions can be set to any supported currency, regardless of a shop's currency.

• Countries can be set independently of the primary market's currency. For example, it's possible to combine Canada and USD.

• Price lists can be created, allowing for fixed prices and percentage adjustments for the primary market.

  Apps might need to be updated if they previously assumed that the primary market's currency and country were the same.

Anchor to Deprecated fields on the Customer objectDeprecated fields on the Customer object

As of API version 2023-10, the following fields on the Customer object have been deprecated:

• averageOrderAmount
• averageOrderAmountV2

Anchor to Deprecated property on the UsageCharge resourceDeprecated property on the UsageCharge resource

The UsageCharge resource's billing_on property has been deprecated.

Anchor to Fulfillment service location name and addressFulfillment service location name and address

Apps can change the name and address of their fulfillment service locations using the GraphQL Admin API's LocationEdit mutation.

The mutation returns a new user error with the CANNOT_MODIFY_ONLINE_ORDER_FULFILLMENT_FOR_FS_LOCATION code if apps attempt to update the fulfillsOnlineOrders field for a fulfillment service location. This field can only be modified on manual locations.

In API version 2023-10, apps require the write_fulfillments access scope to edit a fulfillment service's location. Otherwise, the following error is returned: Access denied for locationEdit field. Required access: write_fulfillments access scope is required to edit the location associated with a fulfillment service.

Anchor to Deprecated field on the ShopResourceLimits objectDeprecated field on the ShopResourceLimits object

The skuResourceLimits field on the GraphQL Admin API's ShopResourceLimits object is deprecated.

We're no longer enforcing a limit of SKUs at the shop level. Instead, use maxProductVariants to determine the limit of variants at the product level.

Anchor to MetafieldDefinitionUpdate mutation: access input type changedMetafieldDefinitionUpdate mutation: access input type changed

The access field on the GraphQL Admin API's MetafieldDefinitionUpdateInput input object has changed from type MetafieldAccessInput to type MetafieldAccessUpdateInput. This is part of a broader API change to introduce support for explicit access grants. Refer to the changelog for details.

Anchor to Simplified metafield interactions with default namespacesSimplified metafield interactions with default namespaces

The namespace field on the GraphQL Admin and Storefront APIs is now optional when you create, update, or query metafields and metafield definitions.

We've updated all relevant mutations and queries to accommodate this change. When an app interacts with metafields, the default namespace is the app-reserved namespace.

Anchor to Deprecated metafield.idDeprecated metafield.id

The metafield(id) query is no longer supported.

Query metafields using the HasMetafields connection of metafield owners. If necessary, you can still query by ID using the Node interface.

Anchor to Primary markets support multiple domainsPrimary markets support multiple domains

The following changes have been introduced to the Markets API:

• A new Market.webPresences connection has been added
• The pre-existing Market.webPresence field now returns the primary domain web presence for a primary market with more than one web presence.
• The marketWebPresenceCreate mutation now enables you to add web presences to the primary market.
• The required marketId argument has been removed from the marketWebPresenceUpdate and marketWebPresenceDelete mutations. Use the new, required `webPresenceId`` argument instead.

Anchor to App Revenue Attribution Record API DepreciatedApp Revenue Attribution Record API Depreciated

The App Revenue Attribution API has been removed.

appRevenueAttributionRecordCreate and appRevenueAttributionRecordDelete are no longer supported in this and future API versions.

This change removes tracking for external app revenue attributions that occur outside of the Billing API. You can now use Google Analytics to track app installations that are driven by Shopify App Store Ads. Link these metrics to external app revenue, to calculate ad-related metrics such as ad-related return on ad spend.

Anchor to Removal of Shop.shopifyPaymentsAccountRemoval of Shop.shopifyPaymentsAccount

We're removing the deprecated Shop.shopifyPaymentsAccount field. Use the shopifyPaymentsAccount query instead.

Anchor to Changes to Subscription Billing Attempt creation behaviorChanges to Subscription Billing Attempt creation behavior

The SubscriptionBillingAttemptCreate mutation now limits the creation of Billing Attempts based on the Fraud Analysis result on the Subscription Contract’s Origin Order.

We've added the CONTRACT_UNDER_REVIEW error code to the GraphQL Admin API's BillingAttemptUserErrorCode enum. This new error code is returned when a Billing Attempt creation is prevented. In previous API versions, this action returned the INVALID error code.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

The following are all the changes introduced in the 2023-10 version of the GraphQL Admin API.

Anchor to New error code added for ,[object Object]New error code added for MetafieldDefinitionUpdate

As of API version 2023-10, we've added the METAOBJECT_DEFINITION_CHANGED error code to the MetafieldDefinitionUpdateUserErrorCode enum. This new error code is returned if you attempt to update a metaobject_reference metafield definition so that it references a different metaobject definition. Previously, this action would result in an INTERNAL_SERVER_ERROR.

Learn more about METAOBJECT_DEFINITION_CHANGED.

Anchor to More order information on the ,[object Object], objectMore order information on the FulfillmentOrder object

As of API version 2023-10, we've added the following fields to the FulfillmentOrder object:

• orderId

• orderName

• orderProcessedAt

• channelId

  With this change, the order information that's required to fulfill an order is accessible on the fulfillmentOrder object with any of the fulfillment_orders access scopes. The same data is available using fulfillmentOrder.order, but this requires the read_orders access scope.

  Learn more about FulfillmentOrder.

Anchor to serviceCode is available on the DeliveryMethod APIserviceCode is available on the DeliveryMethod API

As of the API version 2023-10, you can use the DeliveryMethod object to get the value of the serviceCode chosen for the related FulfillmentOrder. The DeliveryMethod object is now accessible through any of the fulfillment order scopes.

Learn more about DeliveryMethod.

Anchor to Making the primary market more flexibleMaking the primary market more flexible

Anchor to BreakingBreaking

As of API version 2023-10, you can customize the primary market in three new ways:

• The currency can be set to any currency independent of the merchant's shop currency.
• The country can be set independently of the primary market's currency, such that combinations like Canada and USD are now possible.
• Price lists can be created, allowing you to set fixed prices and percentage adjustments for the primary market.

Anchor to Automatic free shipping discountAutomatic free shipping discount

You can now offer automatic free shipping discounts using the discountAutomaticFreeshippingUpdate and discountAutomaticFreeshippingCreate mutations.

Anchor to New webhook topic added for publication delete eventsNew webhook topic added for publication delete events

As of API version 2023-10, a new webhook topic PUBLICATIONS_DELETE is added. This webhook fires whenever a publication is deleted and requires the read_publications scope.

Anchor to New ,[object Object], field on the ,[object Object], objectNew CustomerAccountsV2 field on the Shop object

As of API version 2023-10, you can query the CustomerAccountsV2 field on the Shop object to get information about the shop's customer accounts settings. CustomerAccountsV2 enables you to adapt your app's behaviour to a merchant's customer accounts settings.

Learn more about CustomerAccountsV2.

Anchor to averageOrderAmount fields removed from the Customer objectaverageOrderAmount fields removed from the Customer object

Anchor to BreakingBreaking

As of API version 2023-10, the following Customer fields have been deprecated:

• averageOrderAmount

• averageOrderAmountV2.

  Learn more about the Customer object.

Anchor to [object Object], available on ,[object Object]url available on MediaImage.originalSource

As of API version 2023-10, the url field is available on the MediaImage object's originalSource field.

This will be a signed URL that's valid only for a short period of time. The URL provides access to the uncompressed image that was originally uploaded.

Anchor to Fulfillment constraints built on Shopify FunctionsFulfillment constraints built on Shopify Functions

As of API version 2023-10, you can use the Fulfillment Constraints API for a higher degree of customization when you defined fulfillment and delivery strategies. With this API, checkout won’t return any shipping rates if the configured constraints can’t be met.

For example, you can specify that certain products must be fulfilled from a specific location, based on buyer information, cart information, or metafields.

Learn more about Fulfillment constraints.

Anchor to Apps can now change the name and address of their fulfillment service locationsApps can now change the name and address of their fulfillment service locations

Anchor to BreakingBreaking

As of API version 2023-10, apps can change the name and address of their fulfillment service locations using the LocationEdit mutation.

When a fulfillment service is created, Shopify also creates a new location and associates this with the new fulfillment service. The location inherits its name from the fulfillment service.

Apps can now update the name and address of this location. For example, when a fulfillment service is created, it inherits the country of the shop. If the fulfillment service is located in a different country from the shop, then apps can update the location to accurately reflect the fulfillment service's address.

Anchor to Breaking changesBreaking changes

Anchor to New user error when editing locationsNew user error when editing locations

The LocationEdit mutation will return a new user error with the CANNOT_MODIFY_ONLINE_ORDER_FULFILLMENT_FOR_FS_LOCATION code when you try to update the fulfillsOnlineOrders field for a fulfillment service location. This field can only be modified on manual locations. Fulfillment service locations are always enabled to fulfill online orders.

Anchor to New authorization check when attempting to edit a fulfillment service locationNew authorization check when attempting to edit a fulfillment service location

In API version 2023-10, attempting to edit the location belonging to a fulfillment service without having the write_fulfillments access scope returns the following access denied error:

Earlier API versions returned a user error with the NOT_FOUND code.

Anchor to Breaking changes to ShopResourceLimits API: Deprecate "skuResourceLimits"Breaking changes to ShopResourceLimits API: Deprecate "skuResourceLimits"

Anchor to BreakingBreaking

As of GraphQL Admin API version 2023-10, we're deprecating the "skuResourceLimits" field from the ShopResourceLimits query object. We're no longer enforcing a limit of SKUs at a shop level. Instead, please use "maxProductVariants" to determine the limit of variants at a product level.

Learn more about ShopResourceLimits.

Anchor to Access input type changed on ,[object Object], mutationAccess input type changed on metafieldDefinitionUpdate mutation

Anchor to BreakingBreaking

As of API version 2023-10, we're changing the input field type of MetafieldDefinitionUpdateInput.access from MetafieldAccessInput to MetafieldAccessUpdateInput. This change is part of a broader API change to introduce support for explicit access grants.

Anchor to Simplify metafield interaction with default namespacesSimplify metafield interaction with default namespaces

Anchor to BreakingBreaking

As of API version 2023-10, the GraphQL Admin and Storefront APIs have made the namespace field optional when creating, updating, or querying metafields and metafield definitions. We've updated all relevant mutations and queries to accommodate this change.

Learn more about the GraphQL Admin API and Storefront API documentation for Metafields.

Anchor to Deprecation of ,[object Object], queryDeprecation of metafield(id) query

Anchor to BreakingBreaking

As of API version 2023-10, the metafield(id) query is no longer supported. Metafields should be queried using the HasMetafields connection of metafield owners. If necessary, metafields can be queried by ID using the Node interface.

Anchor to Renderable and online store capabilities for metaobjectsRenderable and online store capabilities for metaobjects

As of API version 2023-10, we're introducing new metaobject capabilities to enable SEO attributes and make entries renderable in the online store. These capabilities make it possible to render landing pages from metaobject entries.

Both capabilities can be enabled and configured independently when creating and updating a metaobject definition.

Anchor to Multiple domains on primary marketsMultiple domains on primary markets

Anchor to BreakingBreaking

As of API version 2023-10, you can have multiple domains on the primary market. The following changes have been introduced to the Markets API:

• New Market.webPresences connection has been added
• Pre-existing Market.webPresence field will return the primary domain web presence for a primary market with multiple web presences
• marketWebPresenceCreate mutation will now allow adding additional web presences to the primary market
• The required marketId argument has been removed from the marketWebPresenceUpdate and marketWebPresenceDelete mutations. The new required webPresenceId argument should be used instead

Anchor to Staff error as an order cancel reasonStaff error as an order cancel reason

As of 2023-10, we have added STAFF to the OrderCancelReason GraphQL type to serve as a reason for canceling orders due to staff errors.

Anchor to New field to query order cancellationsNew field to query order cancellations

As of 2023-10, we've added a new field cancellation to Order graphQL object. This field can provide additional details about the order cancellation, such as staff provided notes on why the order was cancelled. This data is currently available for some orders cancelled on Point of Sale app.

Anchor to Order Routing Location Rule API — Developer PreviewOrder Routing Location Rule API — Developer Preview

The Order Routing Location Rule API is now available in a developer preview. You can use this new Shopify Functions API to write custom order routing rules that determine how to best fulfill and ship orders, based on the needs of the merchant.

Anchor to New compare-at price range field on Product APINew compare-at price range field on Product API

As of version 2023-10 of the GrapqhQL Admin API, we've added the compareAtPriceRange field to Product which will return the minimum and maximum compare-at prices across a product's variants.

Anchor to Manage Quantity Price Breaks for B2B CustomersManage Quantity Price Breaks for B2B Customers

As of the 2023-10 version of the Admin GraphQL API, you can view the quantityPriceBreaks for a product variant on priceListPrice and productVariantContextualPricing. Additionally, you will be able to use the quantityPricingByVariantUpdate mutation to manage quantity price breaks, quantity rules, and fixed prices for multiple variants.

Anchor to App Revenue Attribution Record API DepreciatedApp Revenue Attribution Record API Depreciated

Anchor to BreakingBreaking

As of October 2023, the App Revenue Attribution API has been removed.

appRevenueAttributionRecordCreate and appRevenueAttributionRecordDelete are no longer supported in this and future API versions.

This change removes tracking for external app revenue attributions that occur outside of the Billing API. Partners can now use Google Analytics to track Shopify App Store Ads installs - which can be linked to external app revenue to calculate ad related return on ad spend and other ads related metrics.

Anchor to Removing ,[object Object], on Admin APIRemoving Shop.shopifyPaymentsAccount on Admin API

Anchor to BreakingBreaking

As of 2023-10, we're removing the deprecated Shop.shopifyPaymentsAccount field. Use the shopifyPaymentsAccount query instead.

Anchor to Shopify Protect protection status on Admin APIShopify Protect protection status on Admin API

As of the latest unstable version and upcoming 2023-10 version of the Admin GraphQL API, you can use the shopifyProtect field of Order to view the protection status of Shop Pay orders. The protection status is established asynchronously from the orders/create webhook so you can also listen to the orders/shopify_protect_eligibility_changed webhook to know when the protection status is created or updated.

By providing a clear view of an order’s protection status, we're empowering developers to make more informed decisions. For instance, fraud protection apps can avoid redundant costs for merchants when a Shop Pay order is already protected.

Learn more about Shopify Protect’s protection status on Shopify.dev.

Anchor to Changes to subscription billing attempt creation behaviorChanges to subscription billing attempt creation behavior

Anchor to BreakingBreaking

The SubscriptionBillingAttemptCreate mutation now limits the creation of billing attempts based on the fraud analysis result on the subscription contract’s origin order.

As of API version 2023-10, we've added the CONTRACT_UNDER_REVIEW error code to the BillingAttemptUserErrorCode enum. This new error code is returned in the case where Billing Attempt creation is prevented. In previous API versions, this action will return the INVALID error code.

Learn more about subscription contracts and billing attempts.

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Anchor to Simplify metafield interaction with default namespacesSimplify metafield interaction with default namespaces

Anchor to BreakingBreaking

As of API version 2023-10, the GraphQL Admin and Storefront APIs have made the namespace field optional when creating, updating, or querying metafields and metafield definitions. We've updated all relevant mutations and queries to accommodate this change. When an app interacts with metafields, the default namespace is the app-reserved namespace.

This update does not affect API calls that explicitly specify a namespace. However, it simplifies the process of interacting with namespaces by removing the need to provide a namespace field when the default is suitable. As a result, Apps can now create and query Metafields without the requirement of specifying a namespace.

Learn more in the Admin API and Storefront API documentation for Metafields.

Anchor to Renderable and Online Store capabilities for metaobjectsRenderable and Online Store capabilities for metaobjects

As of API version 2023-10, we're introducing new metaobject capabilities to enable SEO attributes and make entries renderable in the online store. These capabilities make it possible to render landing pages from metaobject entries.

The renderable capability enables setting SEO metadata attributes on your metaobjects. These attributes are accessible in Liquid and via the Storefront API.

The Online Store capability makes your metaobjects render as web pages in the Online Store by assigning a theme template and defining a URL.

Both capabilities can be enabled and configured independently when creating and updating a metaobject definition.

Learn more about the renderable and onlineStore capabilities on Shopify.dev

Anchor to Staff error as Order cancel reasonStaff error as Order cancel reason

As of 2023-10, we have added STAFF to the OrderCancelReason GraphQL type to serve as a reason for canceling orders due to staff errors.

Learn more about OrderCancelReason on Shopify.dev.

Anchor to REST Admin API changesREST Admin API changes

Anchor to Removal of UsageCharge billing_on field on Admin REST APIRemoval of UsageCharge billing_on field on Admin REST API

Anchor to BreakingBreaking

As of API version 2023-10, the UsageCharge resource's billing_on property is deprecated.

Learn more about the UsageCharge resource.

Anchor to Staff error as an order cancel reasonStaff error as an order cancel reason

As of API version 2023-10, we've added STAFF to the OrderCancelReason GraphQL type to serve as a reason for canceling orders due to staff errors.

Learn more about OrderCancelReason.