As of GraphQL Admin API version 2025-01, we're cleaning up the shopifyPaymentsBankAccount endpoint and removing several unused fields.

Merchants using the Storefront API can now offer Combined Listings with Shopify. The Shopify Combined Listings app is available to merchants on Plus plans, helping merchants better merchandise products that come in multiple variations such as colors, materials or lengths, all from the same product listing.

Learn more about the Shopify Combined Listings app in the Shopify Help Center.

As of 2024-10, you can use the recurring_cycle_limit and applies_on_subscription field on the DiscountAutomaticApp object type so that subscriptions can use function based discounts for a specified number of occurrences

Learn more about DiscountAutomaticApp on Shopify.dev.

As of 2024-10, the product create and update webhook payloads contain information indicating if the product has a variant that is a product bundle.

The new boolean field, has_variants_that_requires_components, mirrors what is already available on the Product GraphQL response.

To receive has_variants_that_requires_components in the webhook payload, specify 2024-10 or greater as the webhook API version in your App Partner Dashboard.

Learn more about Product Bundles.

The 2024-10 version of the GraphQL Admin API brings improvements to the StaffMember object:

• New accountType field.
• You can retrieve the staff member making the API request with the currentStaffMember query.
• You can list all staff members with the staffMembers connection query.
• Shop.staffMembers was deprecated in favor of the staffMembers query.

This allows apps using the User REST Admin API resource to migrate to GraphQL's StaffMember object.

As of 2024-10, you can no longer use the deprecated shippingMethods field on the fulfillmentService query or include it as an argument in the fulfillmentOrderSubmitFulfillmentRequest mutation.

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

To learn more see https://help.shopify.com/manual/shipping/fulfillment-services/amazon#activate-fulfillment-by-amazon

As of GraphQL Admin API 2024-10 version, you can make use of a new mutation to create an order.

Learn more about orderCreate on Shopify.dev.

As of October 1, we added the following updates to POS UI Extensions:

• Added support for iOS debugging with the Safari dev tools.
• Added support for the pos.product-details.block.render target.
• Added support for the pos.purchase.post.block.render target.
• Added support for the pos.order-details.block.render target.
• Added support for the pos.customer-details.block.render target.
• Introduced a POSBlock component. It's the required parent component for block extension targets.
• Introduced a POSBlockRow component. It's the required child component for POSBlock, and can be used to wrap other components.
• Deprecated the ActionItem component. Please use the Button component instead.
• Added support for windowed modals.

All of the changes are available for POS UI extensions version 2024-10 and POS app version 9.19.0. See the version log for all version details.

You can now associate a Fulfillment Constraint function with one or multiple delivery method types. The function will only run within the context of those specific delivery methods.

As of Admin GraphQL API version 2024-10 and unstable, you can

• Use the FulfillmentConstraintRuleCreate mutation to register your new Fulfillment Constraint function and associate it with one or multiple delivery methods. A new required input field delivery_method_types will be added.
• Use the FulfillmentConstraintRuleUpdate mutation to update delivery method(s) for an existing registered function.

Existing fulfillment constraint functions will continue to run for SHIPPING, LOCAL and PICKUP_POINT.

As of Admin GraphQL API version 2024-10 and unstable, you can setup your Fulfillment Constraint function to run for Local Pickup delivery method.

Use the FulfillmentConstraintRuleCreate mutation to register your new Fulfillment Constraint function with the PICK_UP delivery method.

Or, use the FulfillmentConstraintRuleUpdate mutation to update your existing registered function to include PICK_UP.

Breaking Changes

As of the Admin API version 2024-10 and unstable release, fulfillmentOrder.destination will return a FulfillmentOrderDestination object instead of null for fulfillment orders lacking an associated shipping address. In such cases, the address related fields within the FulfillmentOrderDestination object will be set to null.

Non Breaking Changes

As of GQL Admin API version 2024-10 and unstable release, you can use new field fulfillmentOrder.destination.location to retrieve the pickup location for the fulfillment order.

You can learn more about fulfillmentOrder.destination here and fulfillmentOrderDestination here

As of 2024-10, we've added a CompanyLocationStaffMemberAssignment to the CompanyLocation object for viewing the staff members assigned to the company location.

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

As of 2024-10, the priceRule resource is being removed. The queries and mutations have been deprecated since 2023-03.

The discount resource can be used to achieve the same operations.

As of GraphQL Admin API version 2024-10, the reverseDeliveryDispose mutation will be deprecated. Use the reverseFulfillmentOrderDispose mutation instead.

Learn more about managing reverse fulfillment orders on Shopify.dev.

As of the 2024-10 API version, you can notify customers that their return request was approved or declined.

You can submit a notifyCustomer argument when approving a return request using the returnApproveRequest mutation.

You can also submit a notifyCustomer argument when declining a return request using the returnDeclineRequest mutation. To include a custom message to the buyer in the email notification, use the declineNote argument.

When notifyCustomer is true, an email notification is sent to the Order.email. If this field is null, the notification is not sent.

As of the 2024-10 Admin GraphQL API, you can use the Refund.orderAdjustments connection to query for the difference between calculated and actual refund amounts. The REFUNDS_CREATE webhook topic will include order adjustments too. As of 2024-10, the webhook payload for REFUNDS_CREATE will not include the kind field.

Please note that the OrderAdjustment.kind field is now deprecated in the Admin GraphQL API. It is also deprecated in the legacy refund.order_adjustments resource in the Admin REST API.

For this reason, refunded shipping costs will not be included in the Refund.orderAdjustments connection. To query for refunded shipping costs, use the Refund.refundShippingLines connection instead. This connection has been updated as of July 18, 2024 to include refunded shipping costs; more info here. Refunded shipping costs will not be present in the webhook payload for REFUNDS_CREATE as of 2024-10 for the same reason.

The OrderAdjustment.kind field will be present on the unstable API version for 6 months to allow apps to migrate to the 2024-10 API version.

As of GraphQL Admin API version 2024-10, the SubscriptionBillingAttempt object will have two new fields: paymentgroupid and paymentsessionid.

This will allow your subscription apps to have better insights into how billing attempts correlate for merchant-facing statistics.

The payment group is defined as: - Attempts belonged to the same subscription contract identity. - The attempts were all failures, or ended in a success. If two sequential successes occur with all the same attributes, then they're treated as separate groups. It can be used for correlated retried billing attempts together.

The payment session for subscriptions is defined as: - Attempts used the same payment group - Attempts used the same payment method - Attempts used the same currency - Attempts were for the same amount We expect any merchant facing statistics regarding payment success rates to only show a single success or failure per paymentsessionid.

As of Payments Apps API version 2024-10, the StartPaymentSession payload for all payment extension types will have one new field: session_id.

This identifier is shared across payment sessions that belong to the same payment group, buyer session, and share payment details. It can be used to power auth rate calculations.

As of Admin GraphQL API version 2024-10, you can access the QueryRoot.discountNodesCount field to retrieve the total count of discounts in the shop.

Learn more about discountNodesCount on Shopify.dev.

We've added a new localized string field displayReason to FulfillmentHold so that you can query for a human-readable reason when a fulfillment is on hold.

As of API version 2024-10, you can use these new fields to TranslatableResourceType that are related to the online store theme: ONLINE_STORE_THEME_JSON_TEMPLATE, ONLINE_STORE_THEME_SECTION_GROUP, ONLINE_STORE_THEME_APP_EMBED, ONLINE_STORE_THEME_LOCALE_CONTENT, ONLINE_STORE_THEME_SETTINGS_CATEGORY and ONLINE_STORE_THEME_SETTINGS_DATA_SECTIONS

Together, these new types will cover the translatable content and translations within the existing ONLINESTORETHEME enum type and offer more granularity with respect to the returned data. They are introduced with the intent of reducing the use of ONLINE_STORE_THEME type in the future, so that we do not return the entirety of a theme's content when it is not needed.

We are also introducing a nestedTranslatableResources connection under TranslatableResource object. When used with a ONLINE_STORE_THEME type TranslatableResource, the theme resources that belong to this particular theme are exposed. -->

As of API version 2024-10, you can use the marketId argument to retrieve translatable content that is specific to a market. Concretely, combined with ONLINE_STORE_THEME_JSON_TEMPLATE and ONLINE_STORE_THEME_SECTION_GROUP translatable resource types, you can retrieve translatable content within the added sections and blocks in a contextualized theme template or theme section group for a specfic market. More details can be found here about customizing a theme for specific markets.

As of GraphQL Admin API version 2024-10, you can use the customerSendAccountInviteEmail mutation to send an email invite to create a classic customer account.

As of GraphQL Admin API version 2024-10, the addressesV2 field is introduced on the Customer object to support paginating through a customer's addresses.

Learn more about the Customer fields on Shopify.dev.

As of 2024-10, you can use the abandonedCheckouts endpoint to get the list of abandoned checkouts of a shop. This will replace the current REST endpoint.

As of API version 2024-10, you can add links to the Orders, Profile, and Settings pages to navigation menus.

To learn more, refer to menuCreate, menuUpdate and menu

As of the 2024-10 release of the GraphQL Customer API, you can now query the following fields for a customer's subscription contracts using the subscriptionContracts or subscriptionContract fields: * linesCount * billingPolicy * deliveryPolicy * deliveryMethod * deliveryPrice * updatedAt * currencyCode

We’ve also added support for the following connections: * lines * orders

The customer_read_own_subscription_contracts permission is now required to query subscription contracts and the customer_write_own_subscription_contracts permission is now required for subscription contract mutations.

Learn more about subscription contracts on the Customer API at Shopify.dev.

As of the GraphQL Admin API version 2024-10, a heldByRequestingApp field is being added to the FulfillmentHold GraphQL resource.

As of the GraphQL Admin API version 2024-10, you will only be able to read the heldBy field on the FulfillmentHold GraphQL resource if you have read_apps scope enabled on your application. Use the heldByRequestingApp boolean field instead if you need to see if your application created the fulfillment hold.

Learn more about FulfillmentHolds.

As of the GraphQL Admin API version 2024-10, the fulfillmentOrderHold mutation will return the fulfillment hold that was created in a new fulfillmentHold return field.

Learn more about the fulfillmentOrderHold mutation.

As of GraphQL API version 2024-10 we will introduce a new enum field for the fulfillmentServiceDelete mutation. The inventoryAction field will allow partners to specifiy the behaviour regarding the inventory when deleting a fulfillment service. The options are:

1. KEEP - this option will convert a Fulfillment Service's locations to be owned by the merchant and therefore the inventory at those locations becomes the responsiblity of the merchant.
2. DELETE - this option, when there are no outstanding fulfillments, will delete the inventory at the location and then the location itself.
3. TRANSFER - this is the existing behaviour, where a destinationLocationId is provided as the destination to relocate the inventory to, before the location is deleted.

If either KEEP or DELETE are provided, it is not possible to also specify a destinationLocationId.

If KEEP is provided, then the merchant must have a sufficient remaining quota of locations on their plan for this operation to succeed, an error will be returned if they do not.

As of 2024-10, the write_third_party_fulfillment_orders access scope permission will change for fulfillment creation. This access scope will no longer allow order management apps to fulfill fulfillment orders assigned to locations owned by other fulfillment service apps. Order management apps will still be able to access and manage these orders, only fulfillment creation will be prohibited.

The write_assigned_fulfillment_orders and write_merchant_managed_fulfillment_orders access scopes will remain unchanged. Fulfillment service apps will continue to be able to fulfill orders assigned to them as long as they have the write_assigned_fulfillment_orders access scope. Fulfillment orders assigned to merchant managed locations will continue to be fulfillable by order management apps as long as they have the write_merchant_managed_fulfillment_orders access scope.

Apps can confirm whether or not fulfillment creation is possible by querying the available supportedActions through either the GraphQL or REST APIs. If the fulfillment order is assigned to a merchant managed location or to the fulfillment service performing the query and it is in a fulfillable state, CREATE_FULFILLMENT will be returned as a possible option.

As of GraphQL Admin API version 2024-10, the CustomerPaymentMethodRevocationReason object has a new enum value: FAILED_TO_RETRIEVE_BILLING_ADDRESS. This value is assigned when a customer payment method is missing the billing address field.

As of 2024-10, we're removing the deprecated productAppendImages, productDeleteImages, productImageUpdate and productReorderImages mutations from public GraphQL API.

Use the productCreateMedia, productDeleteMedia, productUpdateMedia and productReorderMedia mutation instead.

As of Admin API version 2024-10, you can use the created_fulfillment_hold field on fulfillment_orders/placed_on_hold webhook to see the fulfillment hold that was created.

Why was this field added A fulfillment hold gets deleted when a hold is released. It is possible that the FulfillmentOrder.FulfillmentHolds field will be empty by the time the subscriber receives the webhook. The new field created_fulfillment_hold will always show hold that was created regardless of whether it has already been released/deleted.

Learn more about fulfillment_orders/placed_on_hold webhook on Shopify.dev.

As of Webhook API version 2024-10 and unstable, apps can 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.

For example, an app that has enabled Shopify managed install is released with a new configuration that increased the requested scopes from "read_customers" to "read_customers,read_discounts". Once a merchant opens the app and approves the read_discounts access scope this webhook will be emitted with payload:

{
  "id": 1234,
  "previous": [
    "read_customers"
  ],
  "current": [
    "read_customers",
    "read_discounts"
  ],
  "updated_at": "2024-10-01T00:00:00.000Z"
}

Learn more about this webhook on Shopify.dev

As of API version 2024-10, inventory errors about stock levels will no longer be included in the userErrors of cart mutations. Inventory errors will now be available in a new return field, warnings and will contain explicit code values of MERCHANDISE_NOT_ENOUGH_STOCK or MERCHANDISE_OUT_OF_STOCK.

Warnings will be available on all cart mutations to show automatic changes that occurred during the mutation. You can use warnings to manage items in your cart or display information to a buyer. For example, out of stock lines can be easily removed from a cart by using the target field included in the warning as the input to a call to CartLineRemove.

Learn more about cart warnings on Shopify.dev.

As of 2024-10, you can query events by means of eventsCount, event and events.

There has been the addition of an events connection on several types as well, allowing you to query the related events:

• Article
• Blog
• Collection
• Comments
• Pages
• ProductVariants
• Products

There has been one breaking change on the CommentEvent.subject field where we transitioned it to be nullable, null will be returned when the subject's underlying data has been deleted, in the process we also deprected deletionEvents as these are now returned as an Event. When the subject is deleted, the REST API, will also return null for the subject property.

Subscription Status updates can now be run with the bulkOperationRunMutation.

The following mutations have been added: * subscriptionContractActivate * subscriptionContractCancel * subscriptionContractExpire * subscriptionContractFail * subscriptionContractPause

See https://shopify.dev/docs/api/usage/bulk-operations/imports for more information.

As of 2024-10 version of the Admin GraphQL API, the ProductInput object has been split into ProductCreateInput and ProductUpdateInput. The productCreate and productUpdate mutations now accept a new product argument using these types.

The existing input field has been marked deprecated.

Learn more about ProductCreateInput and ProductUpdateInput on Shopify.dev.

As of version 2024-10 of the Admin GraphQL API, you can now read and modify Pages, Articles, Blogs, Comments. Page, Article, and Blog types have replaced the OnlineStorePage, OnlineStoreArticle, and OnlineStoreBlog types in the API.

Pages:

• You can now create new pages using pageCreate, modify existing pages using pageUpdate, and delete pages using pageDelete.
• Pages can be queried using the new page or pages queries.

Articles:

• You can now create new articles using articleCreate, modify existing articles using articleUpdate, and delete articles using articleDelete.
• Articles can be queried using the new article or articles queries.

Blogs:

• You can now create new blogs using blogCreate, modify existing blogs using blogUpdate, and delete blogs using blogDelete.
• Blogs can be queried using the new blog or blogs queries.

Comments:

• You can now modify existing comments using commentApprove, commentSpam, or commentNotSpam. Comments can be deleted with commentDelete.
• Comments can be queried using the new comment or comments queries

App Store ads on the Shopify App Store now support targeting tag-level category pages, in addition to main and sub-category pages. For more information on App Store category page types, see here.

Specifying grants for specific apps on app-owned metafields is now deprecated. New apps will not be able to use this feature effective immediately. Existing apps will continue to have access.

As of API version 2024-10, you can use the admin API to manage Online Store Themes. This feature provides parity with our REST API for managing themes and theme files.

What's New

New queries:

• theme to query an individual theme by ID
• themes to query many themes by role or name

OnlineStoreTheme objects expose a files query which can be used to fetch the metadata and content of files in a theme. Multiple files can be requested at once, speeding up operations that need to fetch many files.

New mutations for themes:

• themeCreate - upload a new theme
• themeDelete - delete an unpublished theme
• themePublish - publish a theme
• themeUpdate - update the name of a theme

New mutations for theme files:

• themeFilesCopy - copy files from one location to another
• themeFilesDelete - delete files in a theme
• themeFilesUpsert - write data to files in a theme

Learn more about these changes on Shopify.dev

As of 2025-01, the default value for the permitsSkuSharing argument in the fulfillmentServiceCreate mutation has been updated to true.

Please be aware that this argument is deprecated and will be removed in the version 2025-04. Consequently, all fulfillment services will be required to permit SKU sharing by default.

As of API version 2024-10, we're launching an API to manage metafield definition capabilities. This new feature provides a flexible and extensible way to define and manage behaviors for metafield definitions across various Shopify features.

What's new?

Metafield definition capabilities can be easily enabled, disabled, and queried through the Admin API

What's next?

In future API versions, we'll be introducing new capabilities to enhance metafield functionality across various Shopify features. Stay tuned for announcements about specific capabilities and how they can benefit your app or integration.

Learn more about metafield capabilities at Shopify.dev

As of API version 2024-10, we're introducing the Metafield Definition Capability Framework and deprecating the use_as_collection_condition field on the Metafield Definition object. The new smart_collection_condition capability will replace the deprecated field, providing a more flexible and extensible way to manage metafield behaviors in smart collections.

What's changing?

• The use_as_collection_condition field on Metafield Definitions is being deprecated.
• A new smart_collection_condition capability is being introduced as part of the Metafield Definition Capability Framework.

Why it matters

The new Capability Framework offers several benefits:

1. Improved flexibility: Capabilities can be easily added, removed, or modified without changing the core Metafield Definition structure.
2. Better extensibility: New capabilities can be introduced in the future without affecting existing implementations.
3. Clearer semantics: Capabilities provide a more explicit way to define metafield behaviors.

How to update

To prepare for this change, update your API calls and app logic as follows:

1. Instead of setting use_as_collection_condition: true, use:

   capabilities: {
     smartCollectionCondition: {
       enabled: true
     }
   }

1. When querying metafield definitions, check the smart_collection_condition capability instead of the use_as_collection_condition field:

   query {
     metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1234") {
       capabilities {
         smartCollectionCondition {
           enabled
         }
       }
     }
   }

Timeline

• API version 2024-10: The new capability is available, and use_as_collection_condition is deprecated but still functional.
• Future version: The use_as_collection_condition field will be removed entirely.

We recommend updating your integrations to use the new capability as soon as possible to ensure a smooth transition.

Learn more about metafield capabilities at Shopify.dev Learn more about the Metafield Definition Capability Framework at Shopify.dev.

As of GraphQL API version 2024-10, we are adding new inventory capabilities in the productSet mutation, in the form of a new field type ProductSetInventoryInput, which allows setting available or on_hand quantities for new and existing product variants on locations specified.

This type can be used in the following contexts:

• ProductSetInput.inventoryQuantities field to specify inventory quantities for products with no custom variants.

• ProductSetVariantInput.inventoryQuantities field to specify inventory quantities for individual custom variants.

For more detailed information and examples, visit our productSet documentation on Shopify.dev.

Today, a new version of Shopify CLI is available, bringing with it a better development experience that streamlines your setup for building Shopify themes.

The update includes the following improvements:

• Instant development server startup, so there's no need to wait for synchronization before opening a browser.
• No dependency on Ruby and unified commands implementation on TypeScript, which streamlines your development cycle with easier install & setup.
• A headless Liquid console, so you can run shopify theme console without opening a browser for authentication.

Learn more about Shopify CLI for themes. Happy coding!

Two new paremeters have been added to the full-funnel theme install event for the Shopify Theme Store - shop_name and shop_url. These enhancements provide more insights on which merchant is installing a theme.

Learn more about the new parameters and full-funnel attribution in the Shopify Theme Store docs.

On the theme listing pages, Google e-commerce events have also been implemented to enhance tracking capabilities. The events view_item and addtocart will now be sent to Google Analytics, allowing for more precise data analysis.

For further details, check out the section on Google e-commerce events in the Shopify Theme Store docs.

As of Shopify CLI 3.67 and Javy 3.1, Shopify Functions built in JavaScript can see improved performance by as much as 40% when combined with @shopify/shopify_function 1.0

Learn more about JavaScript for Shopify Functions on Shopify.dev.