2024-10 release notes

Anchor to HighlightsHighlights

Here are some highlights of version 2024-10 of Shopify's APIs:

• Abandoned checkouts: We've added new types that are associated with the AbandonedCheckout object. This object replaces the Abandoned checkouts resource in the REST Admin API.
• app_scopes/update webhook: Apps can now subscribe to the app/scopes_update webhook topic. This webhook is triggered when the granted access scopes for the installed app on a shop have been modified.
• Cart warnings: Storefront API cart mutations now include warnings to show automatic changes that occurred while executing a mutation.
• Fulfillment constraints: You can now associate a fulfillment constraint function to one or multiple delivery methods, such as SHIPPING and PICKUP. The function will only run under the context of the specified delivery methods.
• Gift cards: You can now use new gift cards and gift card transaction types in all apps and shops, with no additional approval scopes or flags required.
• Metafield capabilities: Create an automated collection based on metafield values for a given definition. Then, filter products based on metafield values for that definition.
• Products query attributes: We've added new attributes to the products query, which include publication_ids, variant_id, and variant_title.
• StaffMember improvements: We've made several improvements to the StaffMember object. These improvements enable apps using the REST Admin API's User resource to migrate to using the GraphQL Admin API's StaffMember object.
• Subscription contracts: New types for subscription contracts are now available in the Customer Account API.

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 Cart warningsCart warnings

Inventory errors about stock levels are no longer included in the userErrors of cart mutations in the Storefront API. Inventory errors are now available in the warnings return field, and contain the following explicit values:

• MERCHANDISE_NOT_ENOUGH_STOCK
• MERCHANDISE_OUT_OF_STOCK

Warnings are available on all cart mutations to show automatic changes that occurred while executing the mutation. You can use warnings to manage items in your cart or display information to a buyer. For example, you can remove out-of-stock lines from a cart by using the target field included in the warning as the input to the cartLinesRemove mutation.

Learn more about cart warnings.

Anchor to Changed enum value for ,[object Object]Changed enum value for OrderDisplayFulfillmentStatus

The OrderDisplayFulfillmentStatus enum now returns a REQUEST_DECLINED value for an order that has had its fulfillment request rejected by a third-party fulfillment service. In API versions prior to 2024-10, orders in the request rejected state return an UNFULFILLED status.

Anchor to Event query enhancementsEvent query enhancements

We've made the CommentEvent.subject field nullable. null is returned when the subject's underlying data has been deleted. You must update your code to handle cases where subject might return null. For example, revise existing logic that assumes the field will always contain data, and implement checks or fallback mechanisms to manage situations where the subject data has been deleted.

We've also deprecated the deletionEvents query in favour of events that indicate deletion. Update your code to remove any reliance on deletionEvents, and use the new event structure. To support querying events, we've added the following types:

Anchor to Fulfillment by AmazonFulfillment by Amazon

As of API version 2024-10, the shippingMethods field on the FulfillmentService object has been deprecated. The shippingMethods argument on the fulfillmentOrderSubmitFulfillmentRequest mutation has also been deprecated.

The shipping method associated with the fulfillment service provider applied only to the Fulfill By Amazon fulfillment service. The Fulfillment by Amazon feature isn't supported as of March 30, 2023. To continue using Amazon fulfillment, merchants need to set up a multi-channel fulfillment solution, as recommended by Amazon.

Anchor to Fulfillment holdsFulfillment holds

As of API version 2024-10, apps can't release fulfillment holds unless they have write access to them. You need to request the following access scopes for your app:

• write_merchant_managed_fulfillment_orders: Allows your app to release holds on fulfillment orders assigned to a merchant-managed location

• write_third_party_fulfillment_orders: Allows your app to release holds on fulfillment orders assigned to a third-party location

• write_marketplace_fulfillment_orders: Allows your app to release holds on fulfillment orders which belong to one of your marketplace's orders

If your app doesn't have sufficient access scopes to release a hold, then a user error with the INVALID_ACCESS code is returned and the hold isn't released.

We've deprecated the fulfillmentOrdersReleaseHolds mutation. Use the fulfillmentOrderReleaseHold mutation instead.

We've also deprecated the GREATER_THAN_ZERO and INVALID_LINE_ITEM_QUANTITY error codes on the fulfillmentOrderReleaseHold mutation.

We've also added the heldByRequestingApp field to the FulfillmentHold object. If you have the read_apps scope enabled on your app, then you'll only be able to read the heldBy field on the FulfillmentHold object. Use the heldByRequestingApp field instead if you need to confirm whether your app created the fulfillment hold.

Additionally, the fulfillmentOrderHold mutation now returns the fulfillment hold that was created in a new fulfillmentHold return field.

Anchor to Gift cardsGift cards

We've improved the GiftCard types and have introduced several new types for working with gift cards. The gift card types are now open to all apps and shops, with no additional approval scopes or flags required.

Developer action required

• The giftCardDisable mutation has been removed. Use giftCardDeactivate instead.
• The disabledAt field on the GiftCard object has been removed. Use the deactivatedAt field instead.

The following types for gift cards are now available:

Anchor to Improvements to the ,[object Object], typeImprovements to the StaffMember type

Shop.staffMembers has been deprecated. Use the staffMembers query instead.

Anchor to Location error codesLocation error codes

We've removed the HAS_OPEN_TRANSFERS_ERROR and FAILED_TO_RELOCATE_OPEN_TRANSFERS error codes from the LocationDeactivateUserErrorCode enum. If you're explicitly checking for either of these error codes in your app, then you should remove references to them.

Anchor to Location resourceLocation resource

If your app retrieves a Location resource using the REST Admin API, then you need to request the read_locations access scope.

If your app reads a Location resource without the read_locations access scope, then a 403 Forbidden error is returned.

Anchor to Metafield definitionsMetafield definitions

We've deprecated the definitions.visibleToStorefrontApi argument on the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable mutations. Use the definitions.access argument on these mutations instead.

Anchor to Online storeOnline store

We've deprecated the OnlineStorePage, OnlineStoreArticle, and OnlineStoreBlog objects. Use the Page, Article, and Blog objects instead.

You can now read and modify pages, articles, blogs, and comments. The following types are now available:

Anchor to Order line itemsOrder line items

We've removed the lineItemsMutable connection on the Order object. Use the lineItems connection on the Order object instead.

Anchor to Order management appsOrder management apps

The write_third_party_fulfillment_orders access scope no longer allows order management apps to fulfill fulfillment orders assigned to locations that are owned by other fulfillment service apps. Order management apps will still be able to access and manage these orders, but fulfillment creation will be prohibited.

The write_assigned_fulfillment_orders and write_merchant_managed_fulfillment_orders access scopes remain unchanged. Fulfillment service apps can still fulfill orders that are assigned to them, as long as they're granted the write_assigned_fulfillment_orders access scope. Fulfillment orders that are assigned to merchant-managed locations are still fulfillable by order management apps, as long as they're granted the write_merchant_managed_fulfillment_orders access scope.

Apps can confirm whether fulfillment creation is possible by querying supported actions using the GraphQL Admin API. If the fulfillment order is assigned to a merchant-managed location or to the fulfillment service performing the query and it's in a fulfillable state, then the CREATE_FULFILLMENT action is returned as a possible option.

Anchor to Pickup locationsPickup locations

You can now use the destination field on the fulfillmentOrder object to retrieve the pickup location for a fulfillment order.

As of API version 2024-10, the destination field returns a FulfillmentOrderDestination object instead of null for fulfillment orders that don't have an associated shipping address. If the fulfillment order doesn't have a shipping address, then the address-related fields within the FulfillmentOrderDestination object are set to null.

Anchor to PriceRule types removedPriceRule types removed

As of API version 2024-10, we've removed PriceRule types from the GraphQL Admin API. The associated queries and mutations have been deprecated since API version 2023-03. Use the discountNode query instead.

The following types have been removed:

• PriceRuleUserError object
• PriceRuleCustomerSelectionInput input object
• PriceRuleDiscountCodeInput input object
• PriceRuleEntitlementToPrerequisiteQuantityRatioInput input object
• PriceRuleInput input object
• PriceRuleItemEntitlementsInput input object
• PriceRuleItemPrerequisitesInput input object
• PriceRuleMoneyRangeInput input object
• PriceRulePrerequisiteToEntitlementQuantityRatioInput input object
• PriceRuleQuantityRangeInput input object
• PriceRuleShippingEntitlementsInput input object
• PriceRuleValidityPeriodInput input object
• PriceRuleValueInput input object
• priceRuleSavedSearches query
• PriceRuleActivate mutation
• PriceRuleCreate mutation
• PriceRuleDeactivate mutation
• PriceRuleDelete mutation
• PriceRuleDiscountCodeCreate mutation
• PriceRuleDiscountCodeUpdate mutation
• PriceRuleUpdate mutation
• priceRule field on the QueryRoot object
• priceRules connection on the QueryRoot object
• priceRules connection on the Shop object
• priceRuleSavedSearches connection on the Shop object

Anchor to Product duplicationsProduct duplications

The productDuplicateAsyncV2 mutation has been removed. We've added the synchronous argument to the productDuplicate mutation, allowing you to choose whether the product duplication should be processed synchronously or asynchronously.

• Asynchronous duplication: By setting the synchronous field to false in the productDuplicate mutation, the operation operates asynchronously, and returns a ProductDuplicateOperation object.
• Operation tracking: You can track the status of the asynchronous duplication by querying the operation ID through the productOperation query.

Anchor to Product inputProduct input

We've removed the input argument on the productCreate and productUpdate mutations.

Use the following product arguments instead:

• ProductCreateInput on the productCreate mutation
• ProductUpdateInput on the productUpdate mutation

Anchor to Product mediaProduct media

We've made changes to how you work with product media by replacing the current media ID inputs with file inputs and expanding media capabilities:

• The mediaIds field on the ProductSetInput input object has been removed. Use the files field instead to associate files to a product.

• The mediaId field on the ProductVariantSetInput input object has been removed. Use the file field instead to associate a file with the product variant.

• The FileSetInput input object is now available for working with existing media and creating new files. This input object is a derivative of the FileCreateInput input object, with an added id field.

Anchor to Product mutationsProduct mutations

We've removed the following deprecated product mutations from the GraphQL Admin API:

• productAppendImages is removed. Use the productCreateMedia mutation instead.
• productDeleteImages is removed. Use the productDeleteMedia mutation instead.
• productImageUpdate is removed. Use the productDeleteMedia. Use the productUpdateMedia mutation instead.
• productReorderImages is removed. Use the productReorderMedia mutation instead.

Anchor to Product variant mutationsProduct variant mutations

We've deprecated the following singular product variant mutations in favor of their equivalent bulk versions:

• productVariantCreate is deprecated. Use the productVariantsBulkCreate mutation instead.

• productVariantUpdate is deprecated. Use the productVariantsBulkUpdate mutation instead.

• productVariantDelete is deprecated. Use the productVariantsBulkDelete mutation instead.

Anchor to ProductImage value removedProductImage value removed

The PRODUCTIMAGE value has been removed from the MetafieldOwnerType enum. Use MEDIA_IMAGE instead.

Anchor to ProductInput fields removedProductInput fields removed

We've removed the following deprecated ProductInput fields from the GraphQL Admin API:

• bodyHTML is removed. Use the descriptionHtml field instead.
• privateMetaFields is removed. Use the productOptions field instead.
• standardizedProductType is removed. Use the category field instead.
• productCategory is removed. Use the category field instead.
• customProductType is removed. Use the category field instead.

Anchor to Removed fields on ,[object Object], objectRemoved fields on ShopFeatures object

The following deprecated fields on the ShopFeatures object have been removed:

• avalaraAvatax

• branding

• captcha

• dynamicRemarketing

• harmonizedSystemCode

• liveView

• onboardingVisual

• reports

• showMetrics

  Instead of the branding field, use Shop.plan.shopifyPlus instead.

Anchor to Removed ,[object Object], on Fulfillment mutationsRemoved V2 on Fulfillment mutations

We've deprecated the fulfillmentCreateV2 and fulfillmentTrackingInfoUpdateV2 mutations. Use the fulfillmentCreate and fulfillmentTrackingInfoUpdate mutations instead. The behavior of the new mutations remains the same as the previous ones. The only change is the removal of V2 to ensure consistent naming across all mutations.

Anchor to Reverse fulfillment ordersReverse fulfillment orders

The reverseDeliveryDispose mutation is deprecated. Use the reverseFulfillmentOrderDispose mutation instead.

The fulfillmentLineItem field on the ReverseFulfillmentOrderLineItem object is now nullable. A ReverseFulfillmentOrderLineItem object won't always be associated with a FulfillmentLineItem object. The non-null fulfillmentLineItem field on API versions prior to 2024-10 returns an error when the fulfillment line item doesn't exist.

Learn more about managing reverse fulfillment orders.

Anchor to Setting available inventory quantitySetting available inventory quantity

We've deprecated the ability to set the available quantity on the inventoryActivate mutation for inventory items that are already in an active state. Use the inventorySetQuantities mutation instead.

We've also added the INVALID_QUANTITY_TOO_LOW value to the InventorySetQuantitiesUserErrorCode enum. The error code is returned if you run the inventorySetQuantities mutation and a quantity is less than negative one billion.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Version 2024-10 of the GraphQL Admin API introduces the following changes:

Anchor to Abandoned checkoutsAbandoned checkouts

We've added new types that are associated with the AbandonedCheckout object. This object replaces the Abandoned checkouts resource in the REST Admin API.

The following new types are available:

Anchor to Adding page links in navigation menusAdding page links in navigation menus

You can now add links to the Orders, Customer profiles, and Settings pages in navigation menus.

You can use the GraphQL Admin API to update menus that include these pages, and add activated full page extensions to menus, when customer account UI extensions are available for general release. Merchants will also be able to customize their customer account navigation menu. For more information, refer to the product roadmap.

To learn more, refer to the following GraphQL reference documentation:

• menuCreate mutation
• menuUpdate mutation
• menu query

Anchor to App feedbackApp feedback

We've added the feedbackGeneratedAt and state fields to the AppFeedback object. This field represents the date and time when the app feedback was generated. It conveys the state of the feedback and whether it requires merchant action.

Anchor to App scopes webhookApp scopes webhook

Apps can now subscribe to the app/scopes_update webhook topic. This webhook is triggered when the granted access scopes for the installed app on a shop have been modified. It allows apps to keep track of the granted access scopes of their installations.

Anchor to Automatic app discountsAutomatic app discounts

We've added the recurringCycleLimit and appliesOnSubscription fields on the DiscountAutomaticApp object and DiscountAutomaticAppInput input object.

The fields enable merchants to use automatic app discounts for subscriptions, and apply the discounts for a pre-determined number of cycles. Developers can use the fields in their automatic app discount functions.

Anchor to Business entitiesBusiness entities

Large merchants with an established international presence need to be able to specify which of their business entities handles sales for a given buyer context. You can now use the GraphQL Admin API to query fields related to the business entities that are enabled on a store.

The following new types are available:

Anchor to Cart and checkout validationsCart and checkout validations

We've added the MAX_VALIDATIONS_ACTIVATED error code to the ValidationUserErrorCode enum. The error code is returned when your app exceeds the maximum of five validation functions in checkout.

Anchor to Cash transactions on POSCash transactions on POS

We've added the totalCashRoundingAdjustment field to the Order object, which allows you to query the total rounding adjustment applied on cash payments or refund transactions in an order on Point of Sale (POS).

Cash transactions on POS are now automatically rounded to the nearest denominations for the some currencies and countries, like CAD (Canada), AUD (Australia), NZD (New Zealand), EUR (Switzerland, Belgium, Finland), DKK (Denmark), Sweden (SEK) and Norway (NOK).

Anchor to Changed enum value for OrderDisplayFulfillmentStatusChanged enum value for OrderDisplayFulfillmentStatus

Anchor to BreakingBreaking

The OrderDisplayFulfillmentStatus enum now returns a REQUEST_DECLINED value for an order that has had its fulfillment request rejected by a third-party fulfillment service. In API versions prior to 2024-10, orders in the request rejected state return an UNFULFILLED status.

Anchor to Collections countCollections count

We've added the collectionsCount query, which enables you to retrieve a count of all collections in a shop. This includes published and unpublished collections, and custom and smart collections.

Anchor to Company location staff membersCompany location staff members

We've added the CompanyLocationStaffMemberAssignment object, which allows you to retrieve staff members assigned to a company location.

You can assign and remove staff members for a company location using the CompanyLocationAssignStaffMembers and CompanyLocationRemoveStaffMembers mutations.

Anchor to Customer account inviteCustomer account invite

You can now use the customerSendAccountInvite mutation to send an email invitation to a customer so that they can create a classic customer account.

We've also added the CustomerSendAccountInviteEmailUserError that defines errors for the customerSendAccountInvite mutation.

Anchor to Customer addresses paginationCustomer addresses pagination

We've added the addressesV2 connection to the Customer object. The addressesV2 connection supports paginating through a customer's addresses, which enables you to retrieve a subset of results at a time.

Anchor to Customer payment methodsCustomer payment methods

We've added the FAILED_TO_RETRIEVE_BILLING_ADDRESS value on the CustomerPaymentMethodRevocationReason enum. The value is returned when a customer payment method is missing the billing address field.

Anchor to Deleting a fulfillment serviceDeleting a fulfillment service

We've introduced the inventoryAction argument on the fulfillmentServiceDelete mutation. You can use the argument to specify how to handle inventory when you delete a fulfillment service. Valid values:

• KEEP: Converts a fulfillment service's locations to be merchant-owned. The inventory at the locations becomes the merchant's responsibility. If KEEP is provided, then the merchant must have a sufficient remaining quota of locations on their Shopify plan for the operation to succeed. Otherwise, an error is returned.

• DELETE: Deletes the inventory at the location and then the location itself. You can only use this option when there are no outstanding fulfillments.

• TRANSFER: Relocates the inventory to a specified destinationLocationId. If you specify either KEEP or DELETE, then you can't also specify a destinationLocationId.

Anchor to Delivery optionsDelivery options

The presentedName field has been added to the DeliveryMethod object. The presentedName field represents the name of the delivery option that was presented to the customer during checkout.

Anchor to Deposits for payment termsDeposits for payment terms

You can now set up a percentage-based deposit requirement for your payment terms using the DepositInput input object. Set up payment terms on company locations using the CompanyCreate, CompanyLocationCreate, and CompanyLocationUpdate mutations.

Learn more about deposits.

Anchor to Discount totalsDiscount totals

You can now query the total number of discounts on a shop, automatic and code-based, using the discountNodesCount query.

Anchor to Duties on ordersDuties on orders

We've added the dutiesIncluded field to Order object.

Anchor to Event query enhancementsEvent query enhancements

Anchor to BreakingBreaking

We've made the CommentEvent.subject field nullable. null is returned when the subject's underlying data has been deleted. You must update your code to handle cases where subject might return null. For example, revise existing logic that assumes the field will always contain data, and implement checks or fallback mechanisms to manage situations where the subject data has been deleted.

We've also deprecated the deletionEvents query in favour of events that indicate deletion. Update your code to remove any reliance on deletionEvents, and use the new event structure. To support querying events, we've added the following types:

Anchor to Filtering ordersFiltering orders

You can now filter orders by the number of items they contain using the subtotalLineItemsQuantity field on the Order object.

You can also filter by an exact number of items, or within a specified range, using the subtotal_line_items_quantity query filter.

Anchor to Filtering productsFiltering products

We've added new attributes to the products query. You can now filter products by the following attributes:

• publication_ids: The IDs of product publications.
• variant_id: The ID of the product variant.
• variant_title: The title of the product variant.

Anchor to Fulfillment by AmazonFulfillment by Amazon

Anchor to BreakingBreaking

As of API version 2024-10, the shippingMethods field on the FulfillmentService object has been deprecated. The shippingMethods argument on the fulfillmentOrderSubmitFulfillmentRequest mutation has also been deprecated.

The shipping method associated with the fulfillment service provider applied only to the Fulfill By Amazon fulfillment service. The Fulfillment by Amazon feature isn't supported as of March 30, 2023. To continue using Amazon fulfillment, merchants need to set up a multi-channel fulfillment solution, as recommended by Amazon.

Anchor to Fulfillment holdsFulfillment holds

Anchor to BreakingBreaking

As of API version 2024-10, apps can't release fulfillment holds unless they have write access to them. You need to request the following access scopes for your app:

• write_merchant_managed_fulfillment_orders: Allows your app to release holds on fulfillment orders assigned to a merchant-managed location

• write_third_party_fulfillment_orders: Allows your app to release holds on fulfillment orders assigned to a third-party location

• write_marketplace_fulfillment_orders: Allows your app to release holds on fulfillment orders which belong to one of your marketplace's orders

If your app doesn't have sufficient access scopes to release a hold, then a user error with the INVALID_ACCESS code is returned and the hold isn't released.

We've deprecated the fulfillmentOrdersReleaseHolds mutation. Use the fulfillmentOrderReleaseHold mutation instead.

We've also deprecated the GREATER_THAN_ZERO and INVALID_LINE_ITEM_QUANTITY error codes on the fulfillmentOrderReleaseHold mutation.

We've added the id field to the FulfillmentHold object. We've also added an optional holdIds argument to the fulfillmentOrderReleaseHold mutation. The holdIds argument enables apps to release a hold by ID, ensuring that only the intended hold is released.

The heldByRequestingApp field is now available on the FulfillmentHold object. As of API version 2024-10, you'll only be able to read the heldBy field on the FulfillmentHold object if you have the read_apps scope enabled on your app. Use the heldByRequestingApp field instead if you need to confirm whether your app created the fulfillment hold.

Additionally, the fulfillmentOrderHold mutation now returns the fulfillment hold that was created in a new fulfillmentHold return field.

As well, we've added a localized, displayReason field to the FulfillmentHold object. You can use this field to query a human-readable reason when a fulfillment is on hold.

Anchor to Fulfillment orders webhookFulfillment orders webhook

You can now use the created_fulfillment_hold field on the fulfillment_orders/placed_on_hold webhook to retrieve the fulfillment hold that was created.

A fulfillment hold is deleted when a hold is released. As a result, it's possible that FulfillmentOrder.FulfillmentHolds is empty by the time the subscriber receives the webhook. The new created_fulfillment_hold field always shows the hold that was created, regardless of whether it has already been released and deleted.

Anchor to Gift cardsGift cards

Anchor to BreakingBreaking

Anchor to Gift cardsGift cards

We've improved the GiftCard types and have introduced several new types for working with gift cards. The gift card types are now open to all apps and shops, with no additional approval scopes or flags required.

Developer action required

• The giftCardDisable mutation has been removed. Use giftCardDeactivate instead.
• The disabledAt field on the GiftCard object has been removed. Use the deactivatedAt field instead.

The following types for gift cards are now available:

Anchor to Improvements to the Shop objectImprovements to the Shop object

We've added the accountOwner field to the Shop object. You can use the field to retrieve information about the account owner of a shop. The accountOwner field returns a StaffMember object.

Anchor to Improvements to the StaffMember typeImprovements to the StaffMember type

Anchor to BreakingBreaking

We've made several improvements to the StaffMember object. These improvements enable apps using the REST Admin API's User resource to migrate to using the GraphQL Admin API's StaffMember object.

• Shop.staffMembers has been deprecated. Use the staffMembers query instead.
• We've added the following new fields to the StaffMember object:
  • accountType
  • bio
  • receiveAnnouncements
  • url
• You can retrieve the staff member making the API request with the currentStaffMember query.

Anchor to Inventory itemsInventory items

You can now use the optional stockAtLegacyLocation argument on the inventoryActivate mutation. Setting the argument to true allows inventory to be activated if the location ID that's provided is associated with a fulfillment service that doesn't permit SKU sharing.

• If an item is activated at a location that doesn't permit SKU sharing, then the item will be deactivated at all other locations.

• If an item is currently active at a location that doesn't permit SKU sharing, and you want to activate that item at another location, then you need to set the stockAtLegacyLocation argument to true.

Anchor to Inventory quantitiesInventory quantities

You can use the ProductSetInventoryInput input object to specify inventory quantities for individual product variants and set available or on_hand quantities for new and existing product variants on locations specified.

Anchor to Linked metafield value error codeLinked metafield value error code

We've added the LINKED_METAFIELD_VALUE_WITHOUT_LINKED_OPTION error code to the ProductOptionsCreateUserError enum. This error code is returned when the linkedMetafieldValue can't be specified for an option that isn't linked to a metafield.

Anchor to Local payment methodsLocal payment methods

We've added the LocalPaymentMethodsPaymentDetails object, which allows you to query the details of a local payment method that's related to a transaction.

Anchor to Location error codesLocation error codes

Anchor to BreakingBreaking

We've removed the HAS_OPEN_TRANSFERS_ERROR and FAILED_TO_RELOCATE_OPEN_TRANSFERS error codes from theLocationDeactivateUserErrorCode enum. If you're explicitly checking for either of these error codes in your app, then you should remove references to them.

Anchor to Metafield capabilitiesMetafield capabilities

Metafield capabilities provide a way to include logic with your metafields. When you create a metafield definition, you can now enable capabilities that provide additional behaviors.

You can enable the following capabilities:

• Smart collection: Create an automated collection based on metafield values for a given definition.

• Admin filterable: Filter products based on metafield values for a definition.

  Learn more about using metafield capabilities.

Anchor to Metafield definitionsMetafield definitions

Anchor to BreakingBreaking

We've deprecated the definitions.visibleToStorefrontApi argument on the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable mutations. Use the definitions.access argument on these mutations instead.

Anchor to Metafield definition webhooksMetafield definition webhooks

You can subscribe to MetafieldDefinition webhook changes under the webhook topics:

• METAFIELD_DEFINITIONS_CREATE
• METAFIELD_DEFINITIONS_UPDATE
• METAFIELD_DEFINITIONS_DELETE

Anchor to Metafield-linked product optionsMetafield-linked product options

In the 2024-04 API version release, we introduced the ability to use the productOptionsCreate, productCreate, and productOptionUpdate mutations to create metafield-linked product options.

As of API version 2024-10, we've added more fields and error codes to support linking metafields to product options.

Available types

Anchor to Metafields support for the cartTransformCreate mutationMetafields support for the cartTransformCreate mutation

We've added the metafields argument to the cartTransformCreate mutation. You can use the argument to set metafields for a CartTransform object at creation without needing to call the metafieldsSet mutation in a subsequent call.

Learn more about the Cart Transform Function API.

Anchor to Online storeOnline store

Anchor to BreakingBreaking

We've deprecated the OnlineStorePage, OnlineStoreArticle, and OnlineStoreBlog objects. Use the Page, Article, and Blog objects instead.

You can now read and modify pages, articles, blogs, and comments. The following types are now available:

Anchor to Optional access scopesOptional access scopes

We've added the optionalAccessScopes field to the App object so that apps can declare some scopes as optional within their configuration. This field allows merchants to progressively grant apps access to data in their store.

Anchor to Order adjustmentsOrder adjustments

We've added the OrderAdjustment object, which represents the difference between a calculated and an actual refund amount. We've also added the orderAdjustment connection on the Refund object, allowing you to retrieve order adjustments that are attached to a refund.

Anchor to Order createOrder create

You can now use the orderCreate mutation to create an order.

Anchor to Order line itemsOrder line items

Anchor to BreakingBreaking

We've removed the lineItemsMutable connection on the Order object. Use the lineItems connection on the Order object instead.

Anchor to Order management appsOrder management apps

Anchor to BreakingBreaking

The write_third_party_fulfillment_orders access scope no longer allows order management apps to fulfill fulfillment orders assigned to locations that are owned by other fulfillment service apps. Order management apps will still be able to access and manage these orders, but fulfillment creation will be prohibited.

The write_assigned_fulfillment_orders and write_merchant_managed_fulfillment_orders access scopes remain unchanged. Fulfillment service apps can still fulfill orders that are assigned to them, as long as they're granted the write_assigned_fulfillment_orders access scope. Fulfillment orders that are assigned to merchant-managed locations are still fulfillable by order management apps, as long as they're granted the write_merchant_managed_fulfillment_orders access scope.

Apps can confirm whether fulfillment creation is possible by querying supported actions using the GraphQL Admin API. If the fulfillment order is assigned to a merchant-managed location or to the fulfillment service performing the query and it's in a fulfillable state, then the CREATE_FULFILLMENT action is returned as a possible option.

Anchor to Order statusOrder status

We've added the statusPageUrl field to the Order object, allowing you to retrieve the URL where the customer can check the order's current status.

Anchor to Pickup locationsPickup locations

Anchor to BreakingBreaking

You can now use the destination field on the fulfillmentOrder object to retrieve the pickup location for a fulfillment order.

As of API version 2024-10, the destination field returns a FulfillmentOrderDestination object instead of null for fulfillment orders that don't have an associated shipping address. If the fulfillment order doesn't have a shipping address, then the address-related fields within the FulfillmentOrderDestination object are set to null.

Anchor to PriceRule types removedPriceRule types removed

Anchor to BreakingBreaking

As of API version 2024-10, we've removed PriceRule types from the GraphQL Admin API. The associated queries and mutations have been deprecated since API version 2023-03. Use the discountNode query instead.

The following types have been removed:

• PriceRuleUserError object
• PriceRuleCustomerSelectionInput input object
• PriceRuleDiscountCodeInput input object
• PriceRuleEntitlementToPrerequisiteQuantityRatioInput input object
• PriceRuleInput input object
• PriceRuleItemEntitlementsInput input object
• PriceRuleItemPrerequisitesInput input object
• PriceRuleMoneyRangeInput input object
• PriceRulePrerequisiteToEntitlementQuantityRatioInput input object
• PriceRuleQuantityRangeInput input object
• PriceRuleShippingEntitlementsInput input object
• PriceRuleValidityPeriodInput input object
• PriceRuleValueInput input object
• priceRuleSavedSearches query
• PriceRuleActivate mutation
• PriceRuleCreate mutation
• PriceRuleDeactivate mutation
• PriceRuleDelete mutation
• PriceRuleDiscountCodeCreate mutation
• PriceRuleDiscountCodeUpdate mutation
• PriceRuleUpdate mutation
• priceRule field on the QueryRoot object
• priceRules connection on the QueryRoot object
• priceRules connection on the Shop object
• priceRuleSavedSearches connection on the Shop object

Anchor to ProductImage value removedProductImage value removed

Anchor to BreakingBreaking

The PRODUCTIMAGE value has been removed from the MetafieldOwnerType enum. Use MEDIA_IMAGE instead.

Anchor to ProductInput fields removedProductInput fields removed

Anchor to BreakingBreaking

We've removed the following deprecated ProductInput fields from the GraphQL Admin API:

• bodyHTML is removed. Use the descriptionHtml field instead.
• privateMetaFields is removed. Use the productOptions field instead.
• standardizedProductType is removed. Use the category field instead.
• productCategory is removed. Use the category field instead.
• customProductType is removed. Use the category field instead.

Anchor to Product deletionsProduct deletions

We've added the synchronous argument to the productDelete mutation. The field allows you to choose whether a product should be deleted synchronously or asynchronously.

• Asynchronous deletion: By setting the synchronous field to false in the productDelete mutation, the operation proceeds asynchronously, and returns a ProductDeleteOperation object.
• Operation tracking: You can track the status of the asynchronous deletion by querying the operation ID through the productOperation query.

Anchor to Product duplicationsProduct duplications

Anchor to BreakingBreaking

The productDuplicateAsyncV2 mutation has been removed. We've added the synchronous argument to the productDuplicate mutation, allowing you to choose whether the product duplication should be processed synchronously or asynchronously.

• Asynchronous duplication: By setting the synchronous field to false in the productDuplicate mutation, the operation operates asynchronously, and returns a ProductDuplicateOperation object.
• Operation tracking: You can track the status of the asynchronous duplication by querying the operation ID through the productOperation query.

Anchor to Product inputProduct input

Anchor to BreakingBreaking

We've removed the input argument on the productCreate and productUpdate mutations.

Use the following product arguments instead:

• ProductCreateInput on the productCreate mutation
• ProductUpdateInput on the productUpdate mutation

Anchor to Product mediaProduct media

Anchor to BreakingBreaking

We've made changes to how you work with product media by replacing the current media ID inputs with file inputs and expanding media capabilities:

• The mediaIds field on the ProductSetInput input object has been removed. Use the files field instead to associate files to a product.

• The mediaId field on the ProductVariantSetInput input object has been removed. Use the file field instead to associate a file with the product variant.

• The FileSetInput input object is now available for working with existing media and creating new files. This input object is a derivative of the FileCreateInput input object, with an added id field.

Anchor to Product mutationsProduct mutations

Anchor to BreakingBreaking

We've removed the following deprecated product mutations from the GraphQL Admin API:

• productAppendImages is removed. Use the productCreateMedia mutation instead.
• productDeleteImages is removed. Use the productDeleteMedia mutation instead.
• productImageUpdate is removed. Use the productUpdateMedia mutation instead.
• productReorderImages is removed. Use the productReorderMedia mutation instead.

Anchor to Product restrictionsProduct restrictions

We've added the restrictedForResource field to the Product object. The field allows you to query product restrictions for a given CalculatedOrder object, and returns both the restricted status and the reason for the restriction.

Anchor to Product taxonomyProduct taxonomy

We've deprecated the PRODUCT_TAXONOMY_NODE_ID value on the CollectionRuleColumn enum, which is used when creating automated collections. Use the PRODUCT_CATEGORY_ID value instead. For more information, refer to the developer changelog.

Anchor to Product variant mutationsProduct variant mutations

Anchor to BreakingBreaking

We've deprecated the following singular product variant mutations in favor of their equivalent bulk versions:

• productVariantCreate is deprecated. Use the productVariantsBulkCreate mutation instead.

• productVariantUpdate is deprecated. Use the productVariantsBulkUpdate mutation instead.

• productVariantDelete is deprecated. Use the productVariantsBulkDelete mutation instead.

Anchor to Product variants countProduct variants count

We've added the productVariantsCount query to the GraphQL Admin API to provide parity with the REST Admin API's ProductVariant count endpoint.

Anchor to Product variants strategyProduct variants strategy

We've added the variantStrategy argument to the productOptionsCreate mutation, which enables more precise control over product variant configuration and inventory management.

The variantStrategy argument includes the following input fields:

• CREATE: Generates new product variants for all possible combinations of option values.
• LEAVE_AS_IS: Updates existing variants to include new option values, without creating new variants.

Anchor to Products webhook topicsProducts webhook topics

The PRODUCTS_CREATE and PRODUCTS_UPDATE webhook payloads now contain the following fields:

• has_variants_that_requires_components: Indicates whether a product has a variant that's a product bundle. The field mirrors the hasVariantsThatRequiresComponents field on the Product object.

• category: Information about the product category associated with a product. The category field exposes a trimmed version of fields that are available on the Product object.

Anchor to Redirects countRedirects count

You can now use the urlRedirectsCount query to retrieve a count of redirects. Previously, this functionality was only available using the REST Admin API.

Anchor to Refunding multiple shipping linesRefunding multiple shipping lines

You can now refund multiple shipping lines using the shipping field on the RefundInput input object or refundShipping field on the ReturnRefundInput input object.

For more information, refer to the developer changelog.

Anchor to Removed fields on ShopFeatures objectRemoved fields on ShopFeatures object

Anchor to BreakingBreaking

The following deprecated fields on the ShopFeatures object have been removed:

• avalaraAvatax
• branding
• captcha
• dynamicRemarketing
• harmonizedSystemCode
• liveView
• onboardingVisual
• reports
• showMetrics

Instead of the branding field, use Shop.plan.shopifyPlus instead.

Anchor to Removed V2 on Fulfillment mutationsRemoved V2 on Fulfillment mutations

Anchor to BreakingBreaking

We've deprecated the fulfillmentCreateV2 and fulfillmentTrackingInfoUpdateV2 mutations. Use the fulfillmentCreate and fulfillmentTrackingInfoUpdate mutations instead.

The behavior of the new mutations remains the same as the previous ones. The only change is the removal of V2 to ensure consistent naming across all mutations.

Anchor to Return approvals and rejectionsReturn approvals and rejections

We've added the notifyCustomer field on the ReturnApproveRequestInput input object and the ReturnDeclineRequestInput input object.

We've also added the declineNote field on the ReturnDeclineRequestInput input object, which represents the notification message that's sent to a customer about their declined return request.

Anchor to Reverse fulfillment ordersReverse fulfillment orders

Anchor to BreakingBreaking

The reverseDeliveryDispose mutation is deprecated. Use the reverseFulfillmentOrderDispose mutation instead.

The fulfillmentLineItem field on the ReverseFulfillmentOrderLineItem object is now nullable. A ReverseFulfillmentOrderLineItem object won't always be associated with a FulfillmentLineItem object. The non-null fulfillmentLineItem field on API versions prior to 2024-10 returns an error when the fulfillment line item doesn't exist.

Learn more about managing reverse fulfillment orders.

Anchor to Rounding adjustments on cash amountsRounding adjustments on cash amounts

We've added the amountRounding field on the OrderTransaction object. The amountRounding field represents the rounding adjustment applied on a cash amount in presentment currency.

Anchor to Setting available inventory quantitySetting available inventory quantity

Anchor to BreakingBreaking

We've deprecated the ability to set the available quantity on the inventoryActivate mutation for inventory items that are already in an active state. Use the inventorySetQuantities mutation instead.

We've also added the INVALID_QUANTITY_TOO_LOW value to the InventorySetQuantitiesUserErrorCode enum. The error code is returned if you run the inventorySetQuantities mutation and a quantity is less than negative one billion.

Anchor to Shop owner nameShop owner name

We've added the shopOwnerName field to the Shop object. The field returns the shop owner's first and last name.

Anchor to Shopify Payments disputesShopify Payments disputes

You can now use the ShopifyPaymentsDispute object to query all Shopify Payments disputes that are associated with a store.

We've also added the ADVANCE and ADVANCE_FUNDING values to the ShopifyPaymentsTransactionType enum.

Anchor to Shopify Payments payoutsShopify Payments payouts

We've added the advanceFees and advanceGross fields to the ShopifyPaymentsPayoutSummary object.

Anchor to Subscription billing attemptsSubscription billing attempts

We've added the transactions connection to the SubscriptionBillingAttempt object. The connection returns the transactions that are created by billing attempts.

Anchor to Subscription contractsSubscription contracts

We've added the lastBillingAttemptErrorType field to the SubscriptionContract object. You can use this field to determine the billing error type when a billing attempt fails.

Anchor to Tender transactionsTender transactions

We've added the order field to the TenderTransaction object. You can use the field to retrieve an order that's related to a transaction with financial impact on a store's balance sheet. If the order has been deleted, then the value is null.

Anchor to Translatable resourcesTranslatable resources

We've added the ONLINE_STORE_THEME_APP_EMBED value to the TranslatableResourceType enum. You can use this value to query the translatable content for an embedded app.

Anchor to REST Admin API changesREST Admin API changes

Version 2024-10 of the REST Admin API introduces the following changes:

Anchor to Business entitiesBusiness entities

Large merchants with an established international presence need to be able to specify which of their business entities handles sales for a given buyer context. You can now use the REST Admin API to request the business entity ID (merchant_business_entity_id) associated with an order.

Anchor to Comment eventsComment events

Anchor to BreakingBreaking

On the Event resource, we now return null when underlying subject data has been deleted. You must update your code to handle null cases. For example, revise existing logic that assumes the field will always contain data, and implement checks or fallback mechanisms to manage situations where subject data has been deleted.

Anchor to Delivery optionsDelivery options

The presented_name property has been added to the FulfillmentOrder resource. The presented_name property represents the name of the delivery option that was presented to the customer during checkout.

Anchor to Location resourceLocation resource

Anchor to BreakingBreaking

If your app retrieves a Location resource, then you need to request the read_locations access scope.

If your app reads a Location resource without the read_locations access scope, then a 403 Forbidden error is returned.

Anchor to Products webhook topicsProducts webhook topics

The products/create and products/update webhook payloads now contain the following properties:

• has_variants_that_requires_components: Indicates whether a product has a variant that's a product bundle
• category: Information about the product category that's associated with a product

Anchor to Refunding multiple shipping linesRefunding multiple shipping lines

You can now refund multiple shipping lines using the Refunds resource in the REST Admin API.

For more information, refer to the developer changelog.

Anchor to Rounding adjustments on cash amountsRounding adjustments on cash amounts

We've added the amount_rounding property on the Transaction resource. The amount_rounding property represents the rounding adjustment applied on a cash amount in presentment currency.

Anchor to Storefront API changesStorefront API changes

Version 2024-10 of the Storefront API introduces the following changes:

Anchor to Cart warningsCart warnings

Anchor to BreakingBreaking

Inventory errors about stock levels are no longer included in the userErrors of cart mutations. Inventory errors are now available in the warnings return field, and contain the following explicit values:

• MERCHANDISE_NOT_ENOUGH_STOCK
• MERCHANDISE_OUT_OF_STOCK

Warnings are available on all cart mutations to show automatic changes that occurred while executing the mutation. You can use warnings to manage items in your cart or display information to a buyer. For example, you can remove out-of-stock lines from a cart by using the target field included in the warning as the input to the cartLinesRemove mutation.

Learn more about cart warnings.

Anchor to Shop Pay installments pricingShop Pay installments pricing

We've added ShopPayInstallmentsPricing fields to the Shop and ProductVariant types. In the future, Hydrogen will support using these fields to display the Shop Pay installments banner on the product page. These require the unauthenticated_read_shop_pay_installments_pricing access scope.

Anchor to Combined listings supportCombined listings support

You can now query combined listings products.

The options field on the Product object returns options and values for both parent and child products. We've also added the following fields to simplify working with complex products:

• Product.adjacentVariants
• Product.selectedOrFirstAvailableVariant
• Product.encodedVariantAvailability
• Product.encodedVariantExistence
• ProductOptionValue.firstSelectableVariant

In the future, you'll be able to use these fields in Hydrogen to build option pickers and display combined listings and other complex products on a storefront.

Anchor to Shopify Function APIs changesShopify Function APIs changes

Version 2024-10 of the Shopify Function APIs introduces the following changes:

Anchor to Fulfillment constraintsFulfillment constraints

You can now associate a fulfillment constraint function to one or multiple delivery methods, such as SHIPPING and PICKUP. The function will only run under the context of the specified delivery methods.

We've added the deliveryMethodTypes field to the FulfillmentConstraintRule object. You can use the fulfillmentConstraintRuleCreate mutation to register your fulfillment constraint function and associate it with one or more delivery methods.

Use the fulfillmentConstraintRuleUpdate mutation to update delivery methods for an existing registered function.

Anchor to Metafields support for the cartTransformCreate mutationMetafields support for the cartTransformCreate mutation

We've added the metafields argument to the cartTransformCreate mutation. You can use the argument to set metafields for a CartTransform object at creation without needing to call the metafieldsSet mutation in a subsequent call.

Learn more about the Cart Transform Function API.

Anchor to Customer Account API changesCustomer Account API changes

Version 2024-10 of the Customer Account API introduces the following changes:

Anchor to Deposits for payment termsDeposits for payment terms

You can now query the percentage-based deposit requirement for your payment terms on company locations.

Learn more about deposits.

Anchor to Subscription contractsSubscription contracts

We've added new types for subscription contracts. The customer_read_own_subscription_contracts permission is now required to query subscription contracts and the customer_write_own_subscription_contracts permission is required to run subscription contracts mutations.

The following new types for managing subscription contracts are available: