2024-10 release notes

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:

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

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.

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.

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.

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:

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

We've added the dutiesIncluded field to Order object.

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:

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

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.

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

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.

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.

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

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

• METAFIELD_DEFINITIONS_CREATE
• METAFIELD_DEFINITIONS_UPDATE
• METAFIELD_DEFINITIONS_DELETE

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

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.

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:

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.

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.

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

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

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.

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.

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.

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

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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

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

For more information, refer to the developer changelog.

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.

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.

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.

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.

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.

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.

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

Learn more about deposits.

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: