---
title: 2024-07 release notes
description: Update your app from API version 2024-04 to 2024-07.
api_name: release-notes
source_url:
  html: https://shopify.dev/docs/api/release-notes/previous-versions/2024-07
  md: https://shopify.dev/docs/api/release-notes/previous-versions/2024-07.md
---

ExpandOn this page

* [Highlights](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#highlights)
* [Breaking changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#breaking-changes)
* [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#graphql-admin-api-changes)
* [REST Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#rest-admin-api-changes)
* [Storefront API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#storefront-api-changes)
* [Shopify Function APIs changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#shopify-function-apis-changes)
* [Customer Account API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#customer-account-api-changes)

# 2024-07 release notes

Note

We're no longer publishing API release notes. Instead, you can find the latest updates on Shopify APIs in our [developer changelog](https://shopify.dev/changelog). You can filter updates by area. For example, you can filter API updates by the API name and version, such as GraphQL Admin API changes in version 2025-04.

| Release date | Date version is no longer supported |
| - | - |
| July 1, 2024 | July 1, 2025 |

***

## Highlights

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

* [Apply discount codes to a draft order](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput) and decide whether to accept automatic discounts when a [draft order is calculated](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCalculate).
* Identify fulfillment orders containing deliveries to [pickup point locations](https://shopify.dev/docs/api/admin-graphql/latest/enums/DeliveryMethodType).
* The [`PRODUCTS_CREATE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-productscreate) and [`PRODUCTS_UPDATE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-productsupdate) webhook payloads now contain information about the media on a product.
* Use the `metafields` and `metafieldDefinitions` connections on the [`OnlineStoreArticle`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreArticle#connections), [`OnlineStoreBlog`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreBlog#connections), and [`OnlineStorePage`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStorePage#connections) objects. Metafields are also now supported on the [`SellingPlan`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SellingPlan) object.
* Use the [`files`](https://shopify.dev/docs/api/admin-graphql/latest/queries/files) query to retrieve 3D models and external videos.
* The [`MobilePlatformApplication`](https://shopify.dev/docs/api/admin-graphql/latest/unions/MobilePlatformApplication) type facilitates the development and operational integration of shared web credentials and app link systems for Shopify mobile apps on both iOS and Android platforms.
* Use the Storefront API to [manage gift cards on a cart](#storefront-api-changes).
* Use the payment customization function to more easily [hide](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/common-objects/hideoperation?api%5Bversion%5D=2024-07) accelerated checkout methods.

***

## Breaking changes

These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.

### Billing attempts

Similar to creating a new order through checkout, the availability of inventory is now checked during the billing attempt process.

If product variants are configured to [prevent overselling](https://help.shopify.com/manual/products/inventory/getting-started-with-inventory/selling-when-out-of-stock) and one or more items in the subscription contract are out of stock, then the billing attempt will fail with the [`INSUFFICIENT_INVENTORY`](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptErrorCode#value-insufficientinventory) error code.

Learn more about [subscription contracts and billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt).

### Cart-level discounts

The `discountedPriceSet` and `discountedPrice` fields on the [`ShippingLine`](https://shopify.dev/docs/api/admin-graphql/2023-07/objects/ShippingLine) object now include cart-level discounts applied to an order, including the free shipping discount, when calculating the discounted price.

In API versions prior to 2024-07, you needed to subtract the `discountAllocations` from `discountedPriceSet` or `discountedPrice` fields to get an accurate value. If you do this in API version 2024-07 and higher, then you'll subtract the same discount twice.

### Cart wallet preferences

We've deprecated the following types in the Storefront API:

* `walletPreferences` argument on the [`CartBuyerIdentityInput`](https://shopify.dev/docs/api/storefront/latest/input-objects/CartBuyerIdentityInput) input object
* `walletPreferences` field on the [`CartBuyerIdentity`](https://shopify.dev/docs/api/storefront/latest/objects/CartBuyerIdentity) object

Use [`CartBuyerIdentityInput.preferences.wallet`](https://shopify.dev/docs/api/storefront/latest/input-objects/CartBuyerIdentityInput#field-cartbuyeridentityinput-preferences) instead.

### Checkout types removed

We've removed checkout types from the Storefront API, following their [deprecation in the 2024-04 API version](https://shopify.dev/docs/api/release-notes/previous-versions/2024-04#deprecations-storefront-api-and-rest-admin-api).

For more information, refer to the [developer changelog](https://shopify.dev/changelog/deprecation-of-checkout-apis).

### Deprecation of REST resources

The [`Checkout`](https://shopify.dev/docs/api/admin-rest/latest/resources/checkout) resource is now deprecated. For more information, refer to the [Developer changelog](https://shopify.dev/changelog/deprecation-of-checkout-apis).

We've also deprecated all endpoints on the [`Country`](https://shopify.dev/docs/api/admin-rest/latest/resources/country) and [`Province`](https://shopify.dev/docs/api/admin-rest/latest/resources/province) resources. For a complete list of affected endpoints, and the GraphQL type equivalents to use instead, refer to the [Developer changelog](https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api).

### Filtering customers

The following [`customer`](https://shopify.dev/docs/api/customer/latest/queries/customer) query filters in the [search syntax](https://shopify.dev/docs/api/usage/search-syntax) have been deprecated:

* `accepts_marketing`
* `city`
* `company`
* `country`
* `customer_date`
* `email_marketing_state`
* `last_abandoned_order_date`
* `order_date`
* `orders_count`
* `province`
* `sms_marketing_state`
* `state`
* `tag`
* `tag_note`
* `territory_code`
* `total_spent`

You can filter customers by these attributes using [segments](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments) instead.

### Inventory item data

Prior to API version 2024-07, you could send inventory item data using [`ProductVariant`](https://shopify.dev/docs/api/admin-graphql/2024-04/objects/ProductVariant#mutations) mutations or on the [`InventoryItemUpdate`](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/inventoryItemUpdate) mutation. Each of these places has a different input object type with very similar fields, and with some fields showing up in one mutation instead of the other.

As of API version 2024-07, the two input types are unified. [`InventoryItemInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/InventoryItemInput) is now the input object type on the [`inventoryItemUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryItemUpdate) mutation instead of the [`InventoryItemUpdateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/InventoryItemUpdateInput) input object.

### Location object

The [`Location`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Location) object is now gated by the `read_locations` access scope. If you attempt to read the `Location` object without the `read_locations` access scope, then an access denied error is returned.

### Marketing activity improvements

You can now use the `urlParameterValue` field as a tracking parameter in the [`marketingActivityCreateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MarketingActivityCreateInput#field-marketingactivitycreateinput-urlparametervalue) and [`marketingActivityUpdateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MarketingActivityUpdateInput#field-marketingactivityupdateinput-urlparametervalue) input objects. This field is currently only available to select partners. Most partners should continue to use UTMs for tracking parameters.

Additionally, the [`MarketingActivityUserError`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketingActivityUserError) enum is now a required type on the `userError` field for the `marketingEngagementCreate` mutation.

### Metafield access controls

Apps can now query the [`access`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-metafielddefinition-access) field of metafield definitions that [they have access to but don't own](https://shopify.dev/docs/apps/build/custom-data/ownership). Previously, an `AuthorizationError` error was returned when accessing the field for metafield definitions that an app didn't have permissions to manage.

Note

Querying the [`grants`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldAccess#field-metafieldaccess-grants) field on the `MetafieldAccess` object still requires permissions to manage the metafield definition and an error is returned if an app queries the field with insufficient permissions.

The `admin` and `storefront` fields on the [`MetafieldAccess`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldAccess#field-metafieldaccess-grants) object now return values in more cases instead of `null`. For example, metafields that don't have associated access grants return `PUBLIC_READ_WRITE` for `admin` access and `LEGACY_LIQUID_ONLY` for `storefront`. In addition, definitions that were created with a storefront access of `NONE` now return `NONE` instead of `null`. As of API version 2024-07, you can set `PUBLIC_READ_WRITE` as the `admin` access control.

Additionally, the `admin` and `storefront` fields on the [`MetafieldAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldAccessInput) input object now use dedicated input enum types, [`MetafieldAdminAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldAdminAccessInput) and [`MetafieldStorefrontAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldStorefrontAccessInput), respectively.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `PUBLIC_READ_WRITE` | Value | Added to the `MetafieldAdminAccess` enum |
| `LEGACY_LIQUID_ONLY` | Value | Added to the `MetafieldStorefrontAccess` enum |
| `MetafieldAdminAccessInput` | Enum | Added |
| `MetafieldStorefrontAccessInput` | Enum | Added |

### Payment method names

Previously, the [`PaymentCustomizationPaymentMethod`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/common-objects/paymentcustomizationpaymentmethod?api%5Bversion%5D=2024-07) object returned multiple payment methods with the name "Shopify Payments" when a store has wallets enabled through Shopify Payments (for example, Apple Pay or Google Pay). This made it impossible for app developers to target the credit card or a specific wallet option for hide, rename, or move operations.

To fix this issue, we've changed the `name` value for wallets to the following values:

| Payment method | API version 2024-04 and lower | API version 2024-07 and higher |
| - | - | - |
| Credit card | `"Shopify Payments"` | `"Shopify Payments"` |
| Apple Pay | `"Shopify Payments"` | `"Apple Pay"` |
| Google Pay | `"Shopify Payments"` | `"Google Pay"` |
| Meta Pay | `"Shopify Payments"` | `"Meta Pay"` |
| Shop Pay | `"Shopify Payments"` | `"Shop Pay"` |

### Product feed variant images

As of API version 2024-07, the variant image field in the `PRODUCT_FEEDS_INCREMENTAL_SYNC` and `PRODUCT_FEEDS_FULL_SYNC` [webhook subscription topics](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic) won't return an image unless one has been set. Previously, the variant image field would return the product's first image when an image wasn't explicitly set for the variant.

If this change doesn't work for your use case, then you can replicate the old behavior by assigning the first product image to the variant.

### Product variants

We've removed several fields on product variants that are duplicates of linked inventory items. For a complete list of changes to the GraphQL Admin API, and to learn more about the types that you can use instead, refer to the [developer changelog](https://shopify.dev/changelog/product-variant-field-cleanup).

### Product taxonomy

We've deprecated the `allProductCategories` field on the `Shop` object. Use the [`allProductCategoriesList`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#field-shop-allproductcategorieslist) field on the `Shop` object instead.

### Refunds

Shopify's suggestion for a refund is now inclusive of payable charges, such as exchange items and fees, alongside returns.

The [`Return.suggestedRefund`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return#field-return-suggestedrefund) query and [`ReturnRefund`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRefund) mutation now have a different expectation on the refund amount. The refund amount considers exchange line items and fees on the return, as well as any outstanding amount owed by the buyer on an order. Previously, the refund amount logic only accounted for return line items.

### Removals of types and fields

We've removed the following types and fields from the GraphQL Admin API:

| Name | Type | Change |
| - | - | - |
| `ShippingLabel` | Object | [Removed](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShippingLabel). |
| `location` field | `Order` object | Removed. Use the `retailLocation` field on the `Order` object instead. |
| `order` field | `CalculatedOrder` object | Removed. Use the `originalOrder` field on the `CalculatedOrder` object instead. |
| `productBased` field | `FulfillmentService` object | [Removed](https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentService). Non-product based fulfillment services are no longer supported. |

We've removed the following types and fields from the Storefront API:

| Name | Type | Change |
| - | - | - |
| `ShopPayPaymentRequestContactFieldInput` | Input object | Removed. Shipping address is now read from the payment method. |
| `shippingAddress` field | `ShopPayPaymentRequestInput` input object | Removed. Shipping address is now read from the payment method. |
| `amount` field | `ShopPayPaymentRequestLineItemInput` input object | Removed. Use the `finalLinePrice` field instead. |
| `amount` field | `ShopPayPaymentRequestLineItem` object | Removed. Use the `finalLinePrice` field instead. |

### Shopify​QL

We've deprecated the [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) query. Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) instead to extract data for your use cases.

### Sorting customers

The following [`CustomerSortKeys`](https://shopify.dev/docs/api/admin-graphql/latest/enums/CustomerSortKeys) are now deprecated:

* `LAST_ORDER_DATE`
* `ORDERS_COUNT`
* `TOTAL_SPENT`

You can order customers by these attributes if you filter customers using [segments](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments).

### Synchronous input improvements for `productSet` mutation

The [`productSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productSet) mutation now defaults to running synchronously unless the input parameter `synchronous` is set to `false`.

We've also increased the input limit on product variants to the existing asynchronous limit. API versions prior to 2024-07 had a limit of 100 variants. You should set `synchronous` to `false` if you need to consider input complexity / size, or are experiencing timeouts.

### Webhook sub-topics

The `subTopic` field has been removed from the [`WebhookSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription) object. Use the [`filter`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription#field-webhooksubscription-filter) field instead.

### Writing metafield values

You can now use the [`metafieldsSet`](https://shopify.dev/docs/api/customer/latest/mutations/metafieldsSet) mutation to assign metafield values on [`Customer`](https://shopify.dev/docs/api/customer/latest/objects/Customer), [`Order`](https://shopify.dev/docs/api/customer/latest/objects/Order), [`Company`](https://shopify.dev/docs/api/customer/latest/objects/Company), and [`CompanyLocation`](https://shopify.dev/docs/api/customer/latest/objects/CompanyLocation) objects.

As part of this change, the Customer Account API needs to be granted explicit read or read/write access to metafield definitions to have access to metafield values. This represents a breaking change because as of API version 2024-07, metafield definitions without [access permissions](#metafield-access-controls) will not be available to the Customer Account API.

***

## Graph​QL Admin API changes

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

### Billing attempts

#### Breaking

Similar to creating a new order through checkout, the availability of inventory is now checked during the billing attempt process.

Where product variants are configured to [prevent overselling](https://help.shopify.com/manual/products/inventory/getting-started-with-inventory/selling-when-out-of-stock) and one or more items in the contract are out of stock, then the billing attempt will fail with the new [`INSUFFICIENT_INVENTORY`](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptErrorCode#value-insufficientinventory) error code.

Learn more about [subscription contracts and billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt).

### Cart-level discounts

#### Breaking

The `discountedPriceSet` and `discountedPrice` fields on the [`ShippingLine`](https://shopify.dev/docs/api/admin-graphql/2023-07/objects/ShippingLine) object now include cart-level discounts applied to an order, including the free shipping discount, when calculating the discounted price.

In API versions prior to 2024-07, you needed to subtract the `discountAllocations` from `discountedPriceSet` or `discountedPrice` fields to get an accurate value. If you do this in API version 2024-07 and higher, then you'll subtract the same discount twice.

### Cash transactions

You can now query the cash transactions that are associated with each cash tracking session. The new [`cashTransactions`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CashTrackingSession#connection-cashtransactions) connection returns all of the cash order transactions that affected the amount in the cash drawer during a cash tracking session.

### Checkout branding

You can use the [`checkoutBrandingUpsert`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert) mutation to configure the styling and visibility of dividers in checkout.

With this change, the dividers below the header, above the footer, between the main and order summary columns, and between sections in the main column can now be customized with visibility, style, and width controls.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `divided` | Field | Added to `CheckoutBrandingFooterInput` input object |
| `divided` | Field | Added to `CheckoutBrandingFooter` object |
| `divided` | Field | Added to `CheckoutBrandingHeaderInput` input object |
| `divided` | Field | Added to `CheckoutBrandingHeader` object |

### Checkout profiles

You can now query the [`typOspPagesActive`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CheckoutProfile#field-checkoutprofile-typosppagesactive) field on the `CheckoutProfiles` object. The `typOspPagesActive` field returns the status of the [**Thank you** and **Order status** pages](https://shopify.dev/docs/apps/build/checkout/thank-you-order-status) on a checkout profile, providing insight as to whether the pages have enabled [Shopify Extensions in Checkout](https://help.shopify.com/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility).

If `typOspPagesActive` is `true`, then both the **Thank you** and **Order status** pages have enabled Shopify Extensions in Checkout, and render the appropriate [checkout UI extensions](https://shopify.dev/docs/api/checkout-ui-extensions) while also making use of [web pixel extensions](https://shopify.dev/docs/apps/build/marketing-analytics/pixels), and [Functions](https://shopify.dev/docs/api/functions/current). If `typOspPagesActive` is `false`, then the **Thank you** and **Order status** pages still use scripts and other deprecated features.

### Combined listings

[Combined listings](https://shopify.dev/docs/apps/build/product-merchandising/combined-listings) bring together products that are merchandised by an option, such as color, model, or dimension, for enhanced display in the product details page.

As of API version 2024-07, you can use the GraphQL Admin API to [manage combined listings](https://shopify.dev/docs/apps/build/product-merchandising/combined-listings/build-for-combined-listings).

### Data sales and sharing opt-outs

We've added the [`dataSaleOptOut`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/dataSaleOptOut) mutation, which opts a customer out of data sales and sharing, and supports compliance with US state laws like CCPA and CPRA. The `dataSaleOptOut` mutation also applies the opt-out to the [Customer Privacy API](https://shopify.dev/docs/api/customer-privacy).

We've also added the [`dataSaleOptOut`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-customer-datasaleoptout) field to the `Customer` object.

To learn more about data sales and sharing opt-outs, refer to [Configuring customer privacy settings](https://help.shopify.com/manual/privacy-and-security/privacy/customer-privacy-settings/privacy-settings).

### Delivery promise

We've added the [`DeliveryPromiseProvider`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryPromiseProvider) object, which represents an entity, such as a third-party service, that can provide delivery estimates on behalf of a store.

Each `DeliveryPromiseProvider` object is associated with a shop [`Location`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Location).

A `DeliveryPromiseProvider` object can be created or updated using the [`deliveryPromiseProviderUpsert`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryPromiseProviderUpsert) mutation, and retrieved using the [`deliveryPromiseProvider`](https://shopify.dev/docs/api/admin-graphql/latest/queries/deliveryPromiseProvider) query.

### Discounts

[`DraftOrderInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput) now accepts [`discountCodes`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput#field-draftorderinput-discountcodes), [`acceptAutomaticDiscounts`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput#field-draftorderinput-acceptautomaticdiscounts), and [`allowDiscountCodesInCheckout`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput#field-draftorderinput-allowdiscountcodesincheckout). These optional input fields allow you to apply discount codes to a draft order and decide whether to accept automatic discounts when a [draft order is calculated](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCalculate).

We've also added the [`platformDiscounts`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder#field-draftorder-platformdiscounts) field which provides details about how the platform discount has been allocated across the draft order line items, the discount type, its name, and more.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `platformDiscounts` | Field | Added to `DraftOrder` object |
| `discountCodes` | Field | Added to `DraftOrder` object |
| `acceptAutomaticDiscounts` | Field | Added to `DraftOrder` object |
| `allowDiscountCodesInCheckout` | Field | Added to `DraftOrder` object |
| `warnings` | Field | Added to `DraftOrder` object |
| `DraftOrderDiscountNotAppliedWarning` | Object | Added |
| `DraftOrderPlatformDiscountAllocation` | Object | Added |
| `DraftOrderPlatformDiscount` | Object | Added |
| `DraftOrderWarning` | Object | Added |
| `platformDiscounts` | Field | Added to `CalculatedDraftOrder` object |
| `discountCodes` | Field | Added to `CalculatedDraftOrder` object |
| `acceptAutomaticDiscounts` | Field | Added to `CalculatedDraftOrder` object |
| `warnings` | Field | Added to `CalculatedDraftOrder` object |
| `approximateDiscountedUnitPriceSet` | Field | Added to `DraftOrderLineItem` object |
| `DraftOrderPlatformDiscountAllocationTarget` | Union | Added |

### Duplicate product variant values

The [`DUPLICATE_VALUE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/ProductSetUserErrorCode#value-duplicatedvalue) error code has been added to the `ProductSetUserErrorCode` enum.

The `id` field on the [`ProductVariantSetInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/ProductVariantSetInput) input object now has validation support to prevent duplicate values. This enhancement ensures that there are no collisions when updating variants.

### Exchanges

You can now use the GraphQL Admin API to interact with exchanges.

The [`returnCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCreate) mutation can now take exchange line items with optional discounts, return shipping fees, and restocking fees to be applied to return lines. A return with exchange line items will also create a new [`FulfillmentOrder`](https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder) for the new items to be sent to the customer.

Note

Canceling a return does affect the fulfillment of exchange items. [Learn more about how exchanges are processed](https://help.shopify.com/manual/orders/refunds-returns/creating-returns#restock-and-fulfill).

You can use the [`returnLineItemRemoveFromReturn`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnLineItemRemoveFromReturn) mutation to remove return lines from a return. With [returns creating sales](https://shopify.dev/changelog/return-mutation-will-update-sales-previously-unchanged-until-time-of-refund), removing a return line from a return will also reversely impact return sales.

Additionally, you can use the [`returnCalculate`](https://shopify.dev/docs/api/admin-graphql/latest/queries/returnCalculate) query to calculate financials before return creation, including inputs for return lines, exchange lines, fees and discounts. [Learn how to use the `returnCalculate` query](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management#step-2-optional-calculate-return-financials).

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `CalculateExchangeLineItemInput` | Input object | Added |
| `CalculateReturnInput` | Input object | Added |
| `CalculateReturnLineItemInput` | Input object | Added |
| `ExchangeLineItemAppliedDiscountInput` | Input object | Added |
| `ExchangeLineItemAppliedDiscountValueInput` | Input object | Added |
| `ExchangeLineItemInput` | Input object | Added |
| `RestockingFeeInput` | Input object | Added |
| `ReturnEditSetRestockingFeeInput` | Input object | Added |
| `ReturnLineItemRemoveFromReturnInput` | Input object | Added |
| `ReturnShippingFeeInput` | Input object | Added |
| `exchangeLineItems` | Field | Added to `ReturnInput` input object |
| `returnShippingFee` | Field | Added to `ReturnInput` input object |
| `restockingFee` | Field | Added to `ReturnLineItemInput` input object |
| `CalculatedExchangeLineItem` | Object | Added |
| `CalculatedRestockingFee` | Object | Added |
| `CalculatedReturnFee` | Object | Added |
| `CalculatedReturnLineItem` | Object | Added |
| `CalculatedReturnShippingFee` | Object | Added |
| `CalculatedReturn` | Object | Added |
| `ReturnLineItemRemoveFromReturn` | Mutation | Added |

### Filtering customers

#### Breaking

The following [`customer`](https://shopify.dev/docs/api/customer/latest/queries/customer) query filters in the [search syntax](https://shopify.dev/docs/api/usage/search-syntax) have been deprecated:

* `accepts_marketing`
* `city`
* `company`
* `country`
* `customer_date`
* `email_marketing_state`
* `last_abandoned_order_date`
* `order_date`
* `orders_count`
* `province`
* `sms_marketing_state`
* `state`
* `tag`
* `tag_note`
* `territory_code`
* `total_spent`

You can filter customers by these attributes using [segments](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments) instead.

### Filter parameters for webhook subscriptions

When you create, update, or query a webhook subscription, you can now include a filter parameter. Filter parameters, which are specified using [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax), allow you to specify conditions as to when webhooks should be emitted for a subscription.

### Fulfillment constraint rules

We've added the [`MAXIMUM_FULFILLMENT_CONSTRAINT_RULES_REACHED`](https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentConstraintRuleCreateUserErrorCode#value-maximumfulfilllmentconstraintrulesreached) error code to the `fulfillmentConstraintRuleCreate` mutation. The error code is returned when you add more than a maximum of ten fulfillment constraint rules to a store.

### Fulfillment orders

You can now access assigned fulfillment orders from the [`assignedFulfillmentOrders`](https://shopify.dev/docs/api/admin-graphql/latest/objects/queryroot#connection-assignedfulfillmentorders) connection on the `QueryRoot` object instead of from the pre-existing [`assignedFulfillmentOrders`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#connection-assignedfulfillmentorders) connection on the `Shop` object. This change includes the deprecation of the `Shop.assignedFulfillmentOrders` query in favour of the newly added `QueryRoot.assignedFulfillmentOrders` query.

The [`DeliveryMethodType`](https://shopify.dev/docs/api/admin-graphql/latest/enums/DeliveryMethodType) enum also now includes the `PICKUP_POINT` value to identify [fulfillment orders](https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder#field-fulfillmentorder-deliverymethod) containing deliveries to pickup point locations.

[Learn how to generate pickup point options](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/delivery-methods/generate-pickup-points).

### Fulfillment order line items

The [`variant`](https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrderLineItem#field-fulfillmentorderlineitem-variant) field has been added to the `FulfillmentOrderLineItem` object.

The field enables order management apps to reference the specific product details that are related to each fulfillment order line item without needing to directly compare SKUs in the order line items.

[Learn more about order management apps](https://shopify.dev/docs/apps/build/orders-fulfillment#order-management-apps).

### Graph​QL completeness

We've added new types to the GraphQL Admin API to provide parity with the following REST resources: [`CarrierService`](https://shopify.dev/docs/api/admin-rest/latest/resources/carrierservice), [`Customer`](https://shopify.dev/docs/api/admin-rest/latest/resources/customer), [`Fulfillment`](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillment), [`FulfillmentEvent`](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillmentevent), [`FulfillmentService`](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillmentservice), [`InventoryItem`](https://shopify.dev/docs/api/admin-rest/latest/resources/inventoryitem), [`Location`](https://shopify.dev/docs/api/admin-rest/latest/resources/location), [`Order`](https://shopify.dev/docs/api/admin-rest/latest/resources/order), and [`Product`](https://shopify.dev/docs/api/admin-rest/latest/resources/product).

| Name | Type | Change |
| - | - | - |
| `DeliveryCarrierServiceCreateInput` | Input object | Added |
| `DeliveryCarrierServiceUpdateInput` | Input object | Added |
| `carrierServiceCreate` | Mutation | Added |
| `carrierServiceUpdate` | Mutation | Added |
| `carrierServiceDelete` | Mutation | Added |
| `active` | Field | Added to the `DeliveryCarrierService` object |
| `supportsServiceDiscovery` | Field | Added to the `DeliveryCarrierService` object |
| `callbackUrl` | Field | Added to the `DeliveryCarrierService` object |
| `carrierServices` | Field | Added to `QueryRoot` object |
| `customersCount` | Query | Added |
| `fulfillmentsCount` | Field | Added to `Order` object |
| `createdAt` | Field | Added to `FulfillmentEvent` object |
| `trackingSupport` | Field | Added to `FulfillmentService` object |
| `InventoryQuantityInput` | Input object | Added |
| `InventorySetQuantitiesInput` | Input object | Added |
| `inventorySetQuantities` | Mutation | Added |
| `locationsCount` | Query | Added |
| `ordersCount` | Query | Added |
| `staffMember` | Field | Added to `Order` object |
| `sourceName` | Field | Added to `Order` object |
| `orderDelete` | Mutation | Added |
| `OrderDeleteUserError` | Object | Added |
| `publishedProductsCount` | Query | Added |
| `webhookSubscriptionsCount` | Query | Added |

### Included fields on webhook subscriptions

The [`includeFields`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription#field-webhooksubscription-includefields) that are specified on a webhook subscription are now available for all webhook topics. Previously, some webhook topics weren't respecting the `includeFields` configuration.

### Improvements to Shop​Policy object

We've added new fields to the [`ShopPolicy`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopPolicy) object. A `ShopPolicy` is a policy that a merchant has configured for their store, such as their refund or privacy policy.

| Name | Type | Change |
| - | - | - |
| `title` | Field | Added |
| `createdAt` | Field | Added |
| `updatedAt` | Field | Added |

### Improvements to Shopify Payments payouts and balance transactions

We've made several improvements to Shopify Payments payouts and balance transactions in the GraphQL Admin API to provide parity with the REST Admin API:

* You can now use [Shopify's API search syntax](https://shopify.dev/docs/api/usage/search-syntax) to filter and sort payouts using the `sortKey` and `savedSearchId` parameters. This functionality allows you to efficiently search and organize payouts based on specific criteria such as `ledger_type`, `status`, `amount`, `currency`, and `issued_at`.

* You can now use the following new fields on the [`ShopifyPaymentsBalanceTransaction`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsBalanceTransaction) object:

  * `sourceID`: Represents the ID of the object that led to the transaction.
  * `sourceOrderTransactionID`: Indicates the ID of the order transaction that triggered the balance transaction. If the `sourceType` is an adjustment, then this value is `null`.
  * `adjustmentOrderTransactions`: An array of associated order transactions that resulted in the balance transaction. If the `sourceType` is not an adjustment, then this array is null. Each object in the array includes `adjustmentReason`, which specifies the reason for the adjustment associated with the transaction. If the `sourceType` is not an adjustment, then value is `null`.

### Inventory error code

The [`LEDGER_DOCUMENT_INVALID`](https://shopify.dev/docs/api/admin-graphql/latest/enums/InventorySetScheduledChangesUserErrorCode#value-ledgerdocumentinvalid) error code has been added to the [`inventorySetScheduledChanges`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventorySetScheduledChanges) mutation. The error code is returned when the `ledgerDocumentUri` provided is not a valid URI.

### Inventory item data

#### Breaking

Prior to API version 2024-07, you could send inventory item data using [`ProductVariant`](https://shopify.dev/docs/api/admin-graphql/2024-04/objects/ProductVariant#mutations) mutations or on the [`InventoryItemUpdate`](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/inventoryItemUpdate) mutation. Each of these places has a different input object type with very similar fields, and with some fields showing up in one mutation instead of the other.

As of API version 2024-07, the two input types are unified. [`InventoryItemInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/InventoryItemInput) is now the input object type on the [`inventoryItemUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryItemUpdate) mutation instead of the [`InventoryItemUpdateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/InventoryItemUpdateInput) input object.

### Location object

#### Breaking

The [`Location`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Location) object is now gated by the `read_locations` access scope. If you attempt to read the `Location` object without the `read_locations` access scope, then an access denied error is returned.

### Marketing activity improvements

#### Breaking

You can now use the `urlParameterValue` field as a tracking parameter in the [`marketingActivityCreateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MarketingActivityCreateInput#field-marketingactivitycreateinput-urlparametervalue) and [`marketingActivityUpdateInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MarketingActivityUpdateInput#field-marketingactivityupdateinput-urlparametervalue) input objects. This field is currently only available to select partners. Most partners should continue to use UTMs for tracking parameters. Additionally, the [`MarketingActivityUserError`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketingActivityUserError) enum is now a required type on the `userError` field for the `marketingEngagementCreate` mutation.

### Media included in product webhooks

The [`PRODUCTS_CREATE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-productscreate) and [`PRODUCTS_UPDATE`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-productsupdate) webhook payloads now contain information about the media on a product.

### Media references

You can now use the [`fileUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileUpdate) mutation to connect files to products.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `referencesToAdd` | Field | Added to `FileUpdateInput` input object |
| `referencesToRemove` | Field | Added to `FileUpdateInput` input object |
| `UNSUPPORTED_FILE_REFERENCE` | Value | Added to `FilesErrorCode` enum |

### Menus on the Online Store

You can now use the GraphQL Admin API to read and modify menus on the Online Store.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `Menu` | Object | Added |
| `MenuItem` | Object | Added |
| `MenuItemCreateInput` | Input object | Added |
| `MenuItemUpdateInput` | Input object | Added |
| `menuCreate` | Mutation | Added |
| `menuUpdate` | Mutation | Added |
| `menuDelete` | Mutation | Added |
| `menu` | Query | Added |
| `menus` | Query | Added |
| `MenuItemType` | Enum | Added |
| `menu` | Field | Added to `QueryRoot` object |

### Metafield access controls

#### Breaking

Apps can now query the [`access`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-metafielddefinition-access) field of metafield definitions that [they have access to but don't own](https://shopify.dev/docs/apps/build/custom-data/ownership). Previously, an `AuthorizationError` error was returned when accessing the field for metafield definitions that an app didn't have permissions to manage.

Note

Querying the [`grants`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldAccess#field-metafieldaccess-grants) field on the `MetafieldAccess` object still requires permissions to manage the metafield definition and an error is returned if an app queries the field with insufficient permissions.

The `admin` and `storefront` fields on the [`MetafieldAccess`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldAccess#field-metafieldaccess-grants) object now return values in more cases instead of `null`. For example, metafields that don't have associated access grants return `PUBLIC_READ_WRITE` for `admin` access and `LEGACY_LIQUID_ONLY` for `storefront`. In addition, definitions that were created with a storefront access of `NONE` now return `NONE` instead of `null`. As of API version 2024-07, you can set `PUBLIC_READ_WRITE` as the `admin` access control.

Additionally, the `admin` and `storefront` fields on the [`MetafieldAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldAccessInput) input object now use dedicated input enum types, [`MetafieldAdminAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldAdminAccessInput) and [`MetafieldStorefrontAccessInput`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldStorefrontAccessInput), respectively.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `PUBLIC_READ_WRITE` | Value | Added to the `MetafieldAdminAccess` enum |
| `LEGACY_LIQUID_ONLY` | Value | Added to the `MetafieldStorefrontAccess` enum |
| `MetafieldAdminAccessInput` | Enum | Added |
| `MetafieldStorefrontAccessInput` | Enum | Added |

### Metafield connections for Online​Store objects

You can now use the `metafields` and `metafieldDefinitions` connections on the [`OnlineStoreArticle`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreArticle#connections), [`OnlineStoreBlog`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreBlog#connections), and [`OnlineStorePage`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStorePage#connections) objects. Previously, you could only retrieve metafields and metafield definitions connections using the REST Admin API.

### Metafield definitions and constraints

We've added new types for reading standard conditional metafields and filtering metafield definitions by constraints:

| Name | Type | Change |
| - | - | - |
| `MetafieldDefinitionConstraints` | Object | Added |
| `MetafieldDefinitionConstraintValue` | Object | Added |
| `MetafieldDefinitionConstraintSubtypeIdentifier` | Input object | Added |
| `MetafieldDefinitionConstraintStatus` | Enum | Added |
| `MetafieldDefinitionCreateUserError` | Enum | Added |
| `MetafieldDefinitionUpdateUserError` | Enum | Added |
| `constraints` | Field | Added to `MetafieldDefinition` object |
| `constraintSubtype` | Field | Added to `metafieldDefinitions` query |
| `constraintStatus` | Field | Added to `metafieldDefinitions` query |
| `constraintSubtype` | Argument | Added to `standardMetafieldDefinitionTemplates` query |
| `constraintStatus` | Argument | Added to `standardMetafieldDefinitionTemplates` query |
| `excludeActivated` | Argument | Added to `standardMetafieldDefinitionTemplates` query |

### Metafield error code

We've added a new error code for mutations that set metafields. The [`INTERNAL_ERROR`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode#value-internalerror) error code has been added to the `MetafieldsSetUserErrorCode` enum.

### Metafield JSON value

The [`Metafield`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metafield) and [`MetaobjectField`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectField) objects now have a `jsonValue` field that returns the stored value as a `JSON` scalar.

By using the `jsonValue` field, metafield values that are stored as `JSON` strings don't have to be parsed on the client-side. The field is set for all metafield types and is also available in all [Function APIs](https://shopify.dev/docs/api/functions). The `jsonValue` field can be used in Function input queries to improve function performance and reduce the instructions needed to parse JSON metafield values, which are commonly used for function configuration.

### Metafields reserved namespaces

We've added the [`RESERVED_NAMESPACE_ORPHANED_METAFIELDS`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldDefinitionDeleteUserErrorCode) error code to the `MetafieldDefinitionDelete` mutation.

### Missing payment information for subscriptions

The [`MISSING_CUSTOMER_PAYMENT_METHOD`](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionDraftErrorCode#value-missingcustomerpaymentmethod) error code is now returned when payment information is missing on the [`subscriptionDraftCommit`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionDraftCommit) mutation.

### Metaobjects

We've added the [`DISPLAY_NAME_CONFLICT`](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetaobjectUserErrorCode#value-displaynameconflict) error code value to the `MetaobjectUserErrorCode` enum.

### Online store password protection

You can now retrieve information about the storefront password of an online store using the [`OnlineStorePasswordProtection`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStorePasswordProtection) and [`OnlineStore`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStore) objects.

### Optional fields on Product​Set​Input

The [`variants`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/ProductSetInput#field-productsetinput-variants) and [`productOptions`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/ProductSetInput#field-productsetinput-productoptions) fields on the `ProductSetInput` input object are now optional. In API versions prior to 2024-07, the `variants` and `productOptions` fields were required.

### Order capture

Shopify Plus merchants using Shopify Payments are able to partially capture authorizations more than once. However, you might know that the capture you're about to perform will be the last one. To reflect this, we've added the [`finalCapture`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCaptureInput#field-ordercaptureinput-finalcapture) field to the `orderCaptureInput` input object.

When you know you're capturing an authorization for the last time, setting the `finalCapture` field to `true` releases any uncaptured funds back to your customer. Doing so is likely to increase customer satisfaction and decrease the risk of chargebacks.

For merchants not on the Shopify Plus plan, the `finalCapture` field has no effect: these authorizations can only be captured once, and uncaptured funds are always returned immediately to the customer.

Currently, the `finalCapture` field only applies to transactions made through Shopify Payments. When capturing authorizations processed through other gateways, `finalCapture` must either be omitted, or set to `null`.

### Order transactions

You can now use the [`transactionsCount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-order-transactionscount) field on the `Order` object to return the number of transactions associated with a given order.

We've also added the [`authorizationExpiresAt`](https://shopify.dev/docs/api/admin-graphql/latest/objects/OrderTransaction#field-ordertransaction-authorizationexpiresat) field on the `OrderTransaction` object. The `authorizationExpiresAt` field is available only to stores on a Shopify Plus plan and is populated only for Shopify Payments authorizations.

### Product bundles

We've added the [`customAttributes`](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItemGroup#field-lineitemgroup-customattributes) field on the `LineItemGroup` object, which allows you to query a list of attributes that represent custom features or special requests. A line item group is also known as a bundle.

Apps can now also do the following:

* Retrieve a bundle item's components on a draft order by using the `bundleComponents` field on the [`DraftOrderBundleLineItemComponentInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderBundleLineItemComponentInput#field-draftorderbundlelineitemcomponentinput-bundlecomponents) input object.
* Add a bundle item to a draft order by including the [`bundleComponents`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DraftOrderInput#field-draftorderinput-bundlecomponents) field on the `draftOrderLineItemInput` input object.

Additionally, the [`CartTransform`](https://shopify.dev/docs/api/functions/reference/cart-transform/graphql/common-objects/carttransform) function now automatically runs on all draft orders.

[Learn more about bundles](https://shopify.dev/docs/apps/build/product-merchandising/bundles).

The following new types are available for creating and updating product bundles:

| Name | Type | Change |
| - | - | - |
| `ProductBundleComponentOptionSelectionValue` | Object | Added |
| `ProductBundleComponentOptionSelection` | Object | Added |
| `ProductBundleComponentQuantityOptionValue` | Object | Added |
| `ProductBundleComponentQuantityOption` | Object | Added |
| `ProductBundleComponent` | Object | Added |
| `ProductBundleOperation` | Object | Added |
| `ProductBundleMutationUserError` | Object | Added |
| `ProductBundleComponentInput` | Input object | Added |
| `ProductBundleComponentOptionSelectionInput` | Input object | Added |
| `ProductBundleComponentQuantityOptionInput` | Input object | Added |
| `ProductBundleComponentQuantityOptionValueInput` | Input object | Added |
| `ProductBundleCreateInput` | Input object | Added |
| `ProductBundleUpdateInput` | Input object | Added |
| `productBundleCreate` | Mutation | Added |
| `productBundleUpdate` | Mutation | Added |
| `ProductBundleComponentOptionSelectionStatus` | Enum | Added |
| `bundleComponents` | Field | Added to `Product` object |

### Product feed variant images

#### Breaking

As of API version 2024-07, the variant image field in the `PRODUCT_FEEDS_INCREMENTAL_SYNC` and `PRODUCT_FEEDS_FULL_SYNC` [webhook subscription topics](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic) won't return an image unless one has been set. Previously, the variant image field would return the product's first image when an image wasn't explicitly set for the variant.

If this change doesn't work for your use case, then you can replicate the old behavior by assigning the first product image to the variant.

### Product options error code

The [`LINKED_METAFIELD_DEFINITION_NOT_FOUND`](https://shopify.dev/docs/api/admin-graphql/latest/enums/ProductOptionUpdateUserErrorCode#value-linkedmetafielddefinitionnotfound) value has been added to the `ProductOptionUpdateUserErrorCode` enum.

### Promise provider data

You can now use the [`sourceReference`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryMethod#field-deliverymethod-sourcereference) field on the `DeliveryMethod` object to return promise provider data associated with a delivery promise.

### Product query

You can now use the `published_at` filter on the [`product`](https://shopify.dev/docs/api/admin-graphql/latest/queries/product) query to determine the date and time when a product was published to the Online Store.

### Product taxonomy

#### Breaking

The following types now have a `category` field, which accepts the global ID (GID) of a taxonomy category that's specified by a merchant:

* [`ProductInput`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/ProductInput#field-productinput-category) input object
* [`Shop`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#field-shop-allproductcategorieslist) object
* [`MetafieldReference`](https://shopify.dev/docs/api/admin-graphql/latest/unions/MetafieldReference#value-product) union

We've also deprecated the `allProductCategories` field on the `Shop` object. Use the [`allProductCategoriesList`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#field-shop-allproductcategorieslist) field on the `Shop` object instead.

### Product translations

You can now use the [`includesTranslations`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/ProductDuplicateAsyncInput#field-productduplicateasyncinput-includetranslations) field on the `ProductDuplicateAsyncInput` input object to specify whether to include translations when running the [`productDuplicateAsyncV2`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDuplicateAsyncV2) mutation.

If `includesTranslations` is set to `true`, then all translations that are saved on the product, its variants, and its metafields are copied over to the new product.

### Product variants

#### Breaking

We've removed several fields on product variants that are duplicates of linked inventory items. For a complete list of changes to the GraphQL Admin API, and to learn more about the types that you can use instead, refer to the [developer changelog](https://shopify.dev/changelog/product-variant-field-cleanup).

### Querying media in files

You can now use the [`files`](https://shopify.dev/docs/api/admin-graphql/latest/queries/files) query to retrieve 3D models and external videos.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `File` | Interface | Added to `Model3d` object |
| `File` | Interface | Added to `ExternalVideo` object |
| `MODEL_3D` | Value | Added to `FileContentType` enum |
| `EXTERNAL_VIDEO` | Value | Added to `FileContentType` enum |

### Removals of types and fields

#### Breaking

We've removed the following types and fields from the GraphQL Admin API:

| Name | Type | Change |
| - | - | - |
| `ShippingLabel` | Object | [Removed](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShippingLabel). |
| `location` field | `Order` object | Removed. Use the `retailLocation` field on the `Order` object instead. |
| `order` field | `CalculatedOrder` object | Removed. Use the `originalOrder` field on the `CalculatedOrder` object instead. |
| `productBased` field | `FulfillmentService` object | [Removed](https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentService). Non-product based fulfillment services are no longer supported. |

### Retail locations

You can now use the [`retailLocation`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-order-retaillocation) field on the `Order` object to query the physical location where a retail order is created or completed.

### Refund line items

You can now use the [`id`](https://shopify.dev/docs/api/admin-graphql/latest/objects/RefundLineItem#field-refundlineitem-id) field on the `RefundLineItem` object to return the global ID of the specified refund line item object.

### Refunds

#### Breaking

Shopify's suggestion for a refund is now inclusive of payable charges, such as exchange items and fees, alongside returns.

The [`Return.suggestedRefund`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return#field-return-suggestedrefund) query and [`ReturnRefund`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRefund) mutation now have a different expectation on the refund amount. The refund amount considers exchange line items and fees on the return, as well as any outstanding amount owed by the buyer on an order. Previously, the refund amount logic only accounted for return line items.

### Returns

As of API version 2024-07, the [`Return.returnLineItems`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return#connection-returnlineitems) connection is an interface type. This change is designed to accommodate more diverse return item types in the future, and provides more flexibility in handling returns.

To maintain compatibility with existing implementations, adjust your queries to use an inline fragment. The following adjustment ensures that queries continue to function correctly with the new interface type:

```graphql
returnLineItems(first: 30) {
  edges {
    cursor
    node {
      ... on ReturnLineItem {
        id
        ...ReturnLineItemAttributes
      }
    }
  }
}
```

### Selling plans

Metafields are now supported on the [`SellingPlan`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SellingPlan) object.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `hasMetafields` | Interface | Added |
| `hasMetafieldDefinitions` | Interface | Added |
| `metafields` | Field | Added to `SellingPlanInput` input object |
| `SELLING_PLAN` | value | Added to `MetafieldOwnerType` enum |
| `INVALID_INPUT` | value | Added to `SellingPlanGroupUserErrorCode` enum |

### Set metafields using compare-and-swap (CAS)

You can now set metafields using compare-and-swap (CAS) with the [`compareDigest`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldsSetInput#field-metafieldssetinput-comparedigest) field on the [`metafieldsSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsSet) mutation. By using CAS, you can properly handle concurrency requests.

### Shopify mobile apps

As of API version 2024-07, we're introducing a new [`MobilePlatformApplication`](https://shopify.dev/docs/api/admin-graphql/latest/unions/MobilePlatformApplication) type. This type facilitates the development and operational integration of shared web credentials and app link systems for Shopify mobile apps on both iOS and Android platforms.

The following new types are available:

| Name | Type | Change |
| - | - | - |
| `AndroidApplication` | Object | Added |
| `AppleApplication` | Object | Added |
| `MobilePlatformApplicationCreateInput` | Input object | Added |
| `MobilePlatformApplication` | Union | Added |
| `mobilePlatformApplicationCreate` | Mutation | Added |
| `MobilePlatformApplicationDelete` | Mutation | Added |
| `MobilePlatformApplicationUpdate` | Mutation | Added |
| `MobilePlatformApplicationUserError` | Enum | Added |
| `mobilePlatformApplication` | Query | Added |
| `mobilePlatformApplications` | Query | Added |

### Shopify Payments balance transactions

| Name | Type | Change |
| - | - | - |
| `ShopifyPaymentsAssociatedOrder` | Object | Added |
| `ShopifyPaymentsBalanceTransactionAssociatedPayout` | Object | Added |
| `amount` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `fee` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `associatedOrder` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `sourceType` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `type` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `associatedPayout` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |
| `test` | Field | Added to `ShopifyPaymentsBalanceTransaction` object |

### Shopify​QL

#### Breaking

We've deprecated the [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) query. Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) instead to extract data for your use cases.

### Sorting customers

#### Breaking

The following [`CustomerSortKeys`](https://shopify.dev/docs/api/admin-graphql/latest/enums/CustomerSortKeys) are now deprecated:

* `LAST_ORDER_DATE`
* `ORDERS_COUNT`
* `TOTAL_SPENT`

You can order customers by these attributes if you filter customers using [segments](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments).

### Store credit at checkout

You can now use the [`StoreCreditAccount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/storeCreditAccount) object to retrieve information about the monetary balance that can be redeemed at checkout for purchases in the store.

### Synchronous input improvement for product​Set mutation

#### Breaking

The [`productSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productSet) mutation now defaults to running synchronously unless the input parameter `synchronous` is set to `false`.

We've also increased the input limit on product variants to the existing asynchronous limit. API versions prior to 2024-07 had a limit of 100 variants. You should set `synchronous` to `false` if you need to consider input complexity / size, or are experiencing timeouts.

### Tax collection improvements

We've added 14 additional [`LocalizationExtensionsKey`](https://shopify.dev/docs/api/admin-graphql/latest/enums/LocalizationExtensionKey) values to support the collection of tax and shipping credentials in several new countries.

### Translatable content types

You can now use the following metafield definition types to save link-related content:

* [`LINK`](https://shopify.dev/docs/api/admin-graphql/latest/enums/LocalizableContentType#value-link): A link consisting of an anchor text and URL
* [`LIST_LINK`](https://shopify.dev/docs/api/admin-graphql/latest/enums/LocalizableContentType#value-listlink): A list of link metafields

[Learn more about metafields](https://shopify.dev/docs/apps/build/custom-data/metafields).

### Validation status for shipping addresses

You can now use the [`validationResultSummary`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MailingAddress#field-mailingaddress-validationresultsummary) field on the `MailingAddress` object to query the validation status of a shipping address. Possible values are `ERROR`, `WARNING`, `NO_ISSUES`, and `NULL`. A `NULL` value indicates that the address has not undergone validation.

[Learn more about how Shopify validates customer addresses](https://help.shopify.com/manual/orders/manage-orders/shipping-address-validation).

### Webhook sub-topics

#### Breaking

The `subTopic` field has been removed from the [`WebhookSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription) object. Use the [`filter`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription#field-webhooksubscription-filter) field instead.

### Webhook topics

We've added the following new webhook topics to the GraphQL Admin API:

| Name | Description |
| - | - |
| `PRODUCT_FEEDS_FULL_SYNC_FINISH` | Triggers when a full sync finishes for a product feed |
| `CUSTOMER_ACCOUNT_SETTINGS_UPDATE` | Triggers when merchants change customer account settings |

***

## REST Admin API changes

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

### Adjustment reason for Shopify Payments transactions

The Shopify Payments [`Transactions`](https://shopify.dev/docs/api/admin-rest/latest/resources/transactions) resource now returns the `adjustment_reason` property to describe the reason an adjustment was made.

### Deprecation of REST resources

#### Breaking

The [`Checkout`](https://shopify.dev/docs/api/admin-rest/latest/resources/checkout) resource is now deprecated. For more information, refer to the [Developer changelog](https://shopify.dev/changelog/deprecation-of-checkout-apis).

We've also deprecated all endpoints on the [`Country`](https://shopify.dev/docs/api/admin-rest/latest/resources/country) and [`Province`](https://shopify.dev/docs/api/admin-rest/latest/resources/province) resources. For a complete list of affected endpoints, and the GraphQL type equivalents to use instead, refer to the [Developer changelog](https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api).

### New properties on the Fulfillment​Order resource

The following properties have been added to `delivery_method` property on the [`FulfillmentOrder`](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillmentorder) resource:

* `branded_promise`: The branded promise that was presented to the customer during checkout. For example, "Shop Promise".
* `additional_information`: The additional information to consider when performing the delivery.
* `service_code`: A reference to the shipping method.
* `source_reference`: The promise provider data associated with delivery promise.

### Order editing

The [`orders/edited`](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook#event-topics-orders-edited) webhook payload now includes a `committed_at` field. You can use this field to identify when an edit to an order is finalized.

***

## Storefront API changes

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

### Cart billing address

You can now use the [`cartBillingAddressUpdate`](https://shopify.dev/docs/api/storefront/latest/mutations/cartbillingaddressupdate) mutation to associate a billing address with a cart.

### Cart error code

The [`NOTE_TOO_LONG`](https://shopify.dev/docs/api/storefront/latest/enums/CartErrorCode#value-notetoolong) error code is now returned in cart mutations when a note exceeds the maximum limit of 5000 characters.

### Cart wallet preferences

#### Breaking

We've deprecated the following types:

* `walletPreferences` argument on the [`CartBuyerIdentityInput`](https://shopify.dev/docs/api/storefront/latest/input-objects/CartBuyerIdentityInput) input object

* `walletPreferences` field on the [`CartBuyerIdentity`](https://shopify.dev/docs/api/storefront/latest/objects/CartBuyerIdentity) object

  Use [`CartBuyerIdentityInput.preferences.wallet`](https://shopify.dev/docs/api/storefront/latest/input-objects/CartBuyerIdentityInput#field-cartbuyeridentityinput-preferences) instead.

### Checkout types removed

#### Breaking

We've removed checkout types from the Storefront API, following their [deprecation in the 2024-04 API version](https://shopify.dev/docs/api/release-notes/previous-versions/2024-04#deprecations-storefront-api-and-rest-admin-api).

For more information, refer to the [developer changelog](https://shopify.dev/changelog/deprecation-of-checkout-apis).

### Discount computations

We've added the [`targetType`](https://shopify.dev/docs/api/storefront/latest/interfaces/CartDiscountAllocation#field-cartdiscountallocation-targettype) field to the `CartDiscountAllocation` interface. The `targetType` field ensures comprehensive discount calculations, which are crucial for payment integrations.

### Gift cards

You can now manage gift cards on a cart in the following ways:

* **When creating a cart**: Add the `giftCardCodes` field to the [`CartInput`](https://shopify.dev/docs/api/storefront/latest/input-objects/cartinput) input object.

* **After a cart is created**: Run the [`cartGiftCardCodesUpdate`](https://shopify.dev/docs/api/storefront/latest/mutations/cartGiftCardCodesUpdate) mutation.

* **Querying for applied gift cards**: Use the [`appliedGiftCards`](https://shopify.dev/docs/api/storefront/latest/objects/Cart#field-cart-appliedgiftcards) field.

  The following new types are available:

  | Name | Type | Change |
  | - | - | - |
  | `cartGiftCardCodesUpdate` | Mutation | Added |
  | `giftCardCodes` | Field | Added to `CartInput` |
  | `appliedGiftCards` | Field | Added to `Cart` object |

### Removals of types and fields

#### Breaking

We've removed the following types and fields from the Storefront API:

| Name | Type | Change |
| - | - | - |
| `ShopPayPaymentRequestContactFieldInput` | Input object | Removed. Shipping address is now read from the payment method. |
| `shippingAddress` field | `ShopPayPaymentRequestInput` input object | Removed. Shipping address is now read from the payment method. |
| `amount` field | `ShopPayPaymentRequestLineItemInput` input object | Removed. Use the `finalLinePrice` field instead. |
| `amount` field | `ShopPayPaymentRequestLineItem` object | Removed. Use the `finalLinePrice` field instead. |

### Shop Pay payment request checkouts

You can now use the following types to manage Shop Pay payment request checkouts:

| Name | Type | Change |
| - | - | - |
| `ShopPayPaymentRequestContactField` | Object | Added |
| `ShopPayPaymentRequestDeliveryMethod` | Object | Added |
| `ShopPayPaymentRequestDiscount` | Object | Added |
| `ShopPayPaymentRequestImage` | Object | Added |
| `ShopPayPaymentRequestReceipt` | Object | Added |
| `ShopPayPaymentRequestSession` | Object | Added |
| `ShopPayPaymentRequestShippingLine` | Object | Added |
| `ShopPayPaymentRequestTotalShippingPrice` | Object | Added |
| `ShopPayPaymentRequest` | Object | Added |
| `ShopPayPaymentRequestDeliveryMethodInput` | Input object | Added |
| `ShopPayPaymentRequestDiscountInput` | Input object | Added |
| `ShopPayPaymentRequestImageInput` | Input object | Added |
| `ShopPayPaymentRequestInput` | Input object | Added |
| `ShopPayPaymentRequestLineItemInput` | Input object | Added |
| `ShopPayPaymentRequestLineItem` | Input object | Added |
| `ShopPayPaymentRequestShippingLineInput` | Input object | Added |
| `ShopPayPaymentRequestTotalShippingPriceInput` | Input object | Added |
| `shopPayPaymentRequestSessionCreate` | Mutation | Added |
| `shopPayPaymentRequestSessionSubmit` | Mutation | Added |

### Single-use delivery addresses

Carts now support single-use delivery addresses with the `oneTimeUse` field on the [DeliveryAddressInput](https://shopify.dev/docs/api/storefront/latest/input-objects/DeliveryAddressInput) input object.

You can use the `oneTimeUse` field to pass a delivery address that shouldn't be saved to the customer's account after checkout. For example, you might want to use this field for one-time gifting purposes.

***

## Shopify Function APIs changes

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

### Metafields support on selling plans

The `HasMetafields` interface is now available on the `SellingPlan` object associated with each [Function API](https://shopify.dev/docs/api/functions#available-apis).

### Order Routing Location Rule API

We've added the `lines` field to the [`FulfillmentGroup`](https://shopify.dev/docs/api/functions/reference/order-routing-location-rule/graphql/common-objects/fulfillmentgroup?api%5Bversion%5D=2024-07) object. The `lines` field returns a list of cart lines containing information about the items that are part of the fulfillment group.

### Payment Customization API

API clients installed on Shopify Plus stores can now make use of the optional [`placements`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/common-objects/hideoperation?api%5Bversion%5D=2024-07) argument in the `hide` operation. This allows you to explicitly hide payment methods from the accelerated checkout or payment selection.

[Learn more about payment customization functions](https://shopify.dev/docs/apps/build/checkout/payments).

### Payment method names

#### Breaking

Previously, the [`PaymentCustomizationPaymentMethod`](https://shopify.dev/docs/api/functions/reference/payment-customization/graphql/common-objects/paymentcustomizationpaymentmethod?api%5Bversion%5D=2024-07) object returned multiple payment methods with the name "Shopify Payments" when a store has wallets enabled through Shopify Payments (for example, Apple Pay or Google Pay). This made it impossible for app developers to target the credit card or a specific wallet option for hide, rename, or move operations.

To fix this issue, we've changed the `name` value for wallets to the following values:

| Payment method | API version 2024-04 and lower | API version 2024-07 and higher |
| - | - | - |
| Credit card | "Shopify Payments" | "Shopify Payments" |
| Apple Pay | "Shopify Payments" | "Apple Pay" |
| Google Pay | "Shopify Payments" | "Google Pay" |
| Meta Pay | "Shopify Payments" | "Meta Pay" |
| Shop Pay | "Shopify Payments" | "Shop Pay" |

### Product Discount API

The Product Discount API now supports [`CartLineTarget`](https://shopify.dev/docs/api/functions/reference/product-discounts/graphql/common-objects/cartlinetarget) object, which enables you to apply discounts on specific cart lines. This functionality was historically only possible with Shopify Scripts.

You can use the `CartLineTarget` object to link discounts to attributed cart lines such as upsell products, free gifts with purchase, or buyer customized products.

***

## Customer Account API changes

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

### Financial status of an order

You can now determine whether the financial status of an order is expired using the [`EXPIRED`](https://shopify.dev/docs/api/customer/latest/enums/OrderFinancialStatus#value-expired) value on the `OrderFinancialStatus` enum.

### Set metafields using compare-and-swap (CAS)

You can now set metafields using compare-and-swap (CAS) with the [`compareDigest`](https://shopify.dev/docs/api/customer/latest/input-objects/MetafieldsSetInput#field-metafieldssetinput-comparedigest) field on the [`metafieldsSet`](https://shopify.dev/docs/api/customer/latest/mutations/metafieldsSet) mutation. By using CAS, you can properly handle concurrency requests.

### Store credit at checkout

Customers who are [authenticated with a customer account](https://shopify.dev/docs/api/customer) can now review and spend their [store credit](https://shopify.dev/docs/api/customer/latest/objects/Customer#connection-storecreditaccounts) at checkout.

### Writing metafield values

#### Breaking

You can now use the [`metafieldsSet`](https://shopify.dev/docs/api/customer/latest/mutations/metafieldsSet) mutation to assign metafield values on [`Customer`](https://shopify.dev/docs/api/customer/latest/objects/Customer), [`Order`](https://shopify.dev/docs/api/customer/latest/objects/Order), [`Company`](https://shopify.dev/docs/api/customer/latest/objects/Company), and [`CompanyLocation`](https://shopify.dev/docs/api/customer/latest/objects/CompanyLocation) objects.

As part of this change, the Customer Account API needs to be granted explicit read or read/write access to metafield definitions to have access to metafield values. This represents a breaking change because as of API version 2024-07, metafield definitions without [access permissions](#metafield-access-controls) will not be available to the Customer Account API.

***

* [Highlights](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#highlights)
* [Breaking changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#breaking-changes)
* [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#graphql-admin-api-changes)
* [REST Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#rest-admin-api-changes)
* [Storefront API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#storefront-api-changes)
* [Shopify Function APIs changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#shopify-function-apis-changes)
* [Customer Account API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2024-07#customer-account-api-changes)