2024-07 release notes
We're no longer publishing API release notes. Instead, you can find the latest updates on Shopify APIs in our developer 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 |
Anchor to HighlightsHighlights
Here are some highlights of version 2024-07 of Shopify's APIs:
- Apply discount codes to a draft order and decide whether to accept automatic discounts when a draft order is calculated.
- Identify fulfillment orders containing deliveries to pickup point locations.
- The
PRODUCTS_CREATEandPRODUCTS_UPDATEwebhook payloads now contain information about the media on a product. - Use the
metafieldsandmetafieldDefinitionsconnections on theOnlineStoreArticle,OnlineStoreBlog, andOnlineStorePageobjects. Metafields are also now supported on theSellingPlanobject. - Use the
filesquery to retrieve 3D models and external videos. - The
MobilePlatformApplicationtype 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.
- Use the payment customization function to more easily hide accelerated checkout methods.
Anchor to Breaking changesBreaking changes
These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.
Anchor to Billing attemptsBilling 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 and one or more items in the subscription contract are out of stock, then the billing attempt will fail with the INSUFFICIENT_INVENTORY error code.
Learn more about subscription contracts and billing attempts.
Anchor to Cart-level discountsCart-level discounts
The discountedPriceSet and discountedPrice fields on the 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.
Anchor to Cart wallet preferencesCart wallet preferences
We've deprecated the following types in the Storefront API:
walletPreferencesargument on theCartBuyerIdentityInputinput objectwalletPreferencesfield on theCartBuyerIdentityobject
Use CartBuyerIdentityInput.preferences.wallet instead.
Anchor to Checkout types removedCheckout types removed
We've removed checkout types from the Storefront API, following their deprecation in the 2024-04 API version.
For more information, refer to the developer changelog.
Anchor to Deprecation of REST resourcesDeprecation of REST resources
The Checkout resource is now deprecated. For more information, refer to the Developer changelog.
We've also deprecated all endpoints on the Country and Province resources. For a complete list of affected endpoints, and the GraphQL type equivalents to use instead, refer to the Developer changelog.
Anchor to Filtering customersFiltering customers
The following customer query filters in the search syntax have been deprecated:
accepts_marketingcitycompanycountrycustomer_dateemail_marketing_statelast_abandoned_order_dateorder_dateorders_countprovincesms_marketing_statestatetagtag_noteterritory_codetotal_spent
You can filter customers by these attributes using segments instead.
Anchor to Inventory item dataInventory item data
Prior to API version 2024-07, you could send inventory item data using ProductVariant mutations or on the 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 is now the input object type on the inventoryItemUpdate mutation instead of the InventoryItemUpdateInput input object.
Anchor to Location objectLocation object
The 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.
Anchor to Marketing activity improvementsMarketing activity improvements
You can now use the urlParameterValue field as a tracking parameter in the marketingActivityCreateInput and marketingActivityUpdateInput input objects. This field is currently only available to select partners. Most partners should continue to use UTMs for tracking parameters.
Additionally, the MarketingActivityUserError enum is now a required type on the userError field for the marketingEngagementCreate mutation.
Anchor to Metafield access controlsMetafield access controls
Apps can now query the access field of metafield definitions that they have access to but don't own. Previously, an AuthorizationError error was returned when accessing the field for metafield definitions that an app didn't have permissions to manage.
Querying the 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 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 input object now use dedicated input enum types, MetafieldAdminAccessInput and 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 |
Anchor to Payment method namesPayment method names
Previously, the PaymentCustomizationPaymentMethod 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" |
Anchor to Product feed variant imagesProduct 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 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.
Anchor to Product variantsProduct 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.
Anchor to Product taxonomyProduct taxonomy
We've deprecated the allProductCategories field on the Shop object. Use the allProductCategoriesList field on the Shop object instead.
Anchor to RefundsRefunds
Shopify's suggestion for a refund is now inclusive of payable charges, such as exchange items and fees, alongside returns.
The Return.suggestedRefund query and 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.
Anchor to Removals of types and fieldsRemovals of types and fields
We've removed the following types and fields from the GraphQL Admin API:
| Name | Type | Change |
|---|---|---|
ShippingLabel | Object | Removed. |
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. 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. |
Anchor to ShopifyQLShopify QL
We've deprecated the shopifyqlQuery query. Use the GraphQL Admin API instead to extract data for your use cases.
Anchor to Sorting customersSorting customers
The following CustomerSortKeys are now deprecated:
LAST_ORDER_DATEORDERS_COUNTTOTAL_SPENT
You can order customers by these attributes if you filter customers using segments.
Anchor to Synchronous input improvements for ,[object Object], mutationSynchronous input improvements for productSet mutation
productSet mutationThe 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.
Anchor to Webhook sub-topicsWebhook sub-topics
The subTopic field has been removed from the WebhookSubscription object. Use the filter field instead.
Anchor to Writing metafield valuesWriting metafield values
You can now use the metafieldsSet mutation to assign metafield values on Customer, Order, Company, and 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 will not be available to the Customer Account API.
Anchor to GraphQL Admin API changesGraph QL Admin API changes
Version 2024-07 of the GraphQL Admin API introduces the following changes:
Anchor to Billing attemptsBilling attempts
Anchor to BreakingBreaking
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 and one or more items in the contract are out of stock, then the billing attempt will fail with the new INSUFFICIENT_INVENTORY error code.
Learn more about subscription contracts and billing attempts.
Anchor to Cart-level discountsCart-level discounts
Anchor to BreakingBreaking
The discountedPriceSet and discountedPrice fields on the 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.
Anchor to Cash transactionsCash transactions
You can now query the cash transactions that are associated with each cash tracking session. The new cashTransactions connection returns all of the cash order transactions that affected the amount in the cash drawer during a cash tracking session.
Anchor to Checkout brandingCheckout branding
You can use the 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 |
Anchor to Checkout profilesCheckout profiles
You can now query the typOspPagesActive field on the CheckoutProfiles object. The typOspPagesActive field returns the status of the Thank you and Order status pages on a checkout profile, providing insight as to whether the pages have enabled Shopify Extensions in Checkout.
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 while also making use of web pixel extensions, and Functions. If typOspPagesActive is false, then the Thank you and Order status pages still use scripts and other deprecated features.
Anchor to Combined listingsCombined listings
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.
Anchor to Data sales and sharing opt-outsData sales and sharing opt-outs
We've added the 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.
We've also added the dataSaleOptOut field to the Customer object.
To learn more about data sales and sharing opt-outs, refer to Configuring customer privacy settings.
Anchor to Delivery promiseDelivery promise
We've added the 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.
A DeliveryPromiseProvider object can be created or updated using the deliveryPromiseProviderUpsert mutation, and retrieved using the deliveryPromiseProvider query.
Anchor to DiscountsDiscounts
DraftOrderInput now accepts discountCodes, acceptAutomaticDiscounts, and 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.
We've also added the 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 |
Anchor to Duplicate product variant valuesDuplicate product variant values
The DUPLICATE_VALUE error code has been added to the ProductSetUserErrorCode enum.
The id field on the ProductVariantSetInput input object now has validation support to prevent duplicate values. This enhancement ensures that there are no collisions when updating variants.
Anchor to ExchangesExchanges
You can now use the GraphQL Admin API to interact with exchanges.
The 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 for the new items to be sent to the customer.
Canceling a return does affect the fulfillment of exchange items. Learn more about how exchanges are processed.
You can use the returnLineItemRemoveFromReturn mutation to remove return lines from a return. With returns creating sales, removing a return line from a return will also reversely impact return sales.
Additionally, you can use the 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.
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 |
Anchor to Filtering customersFiltering customers
Anchor to BreakingBreaking
The following customer query filters in the search syntax have been deprecated:
accepts_marketingcitycompanycountrycustomer_dateemail_marketing_statelast_abandoned_order_dateorder_dateorders_countprovincesms_marketing_statestatetagtag_noteterritory_codetotal_spent
You can filter customers by these attributes using segments instead.
Anchor to Filter parameters for webhook subscriptionsFilter 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, allow you to specify conditions as to when webhooks should be emitted for a subscription.
Anchor to Fulfillment constraint rulesFulfillment constraint rules
We've added the MAXIMUM_FULFILLMENT_CONSTRAINT_RULES_REACHED 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.
Anchor to Fulfillment ordersFulfillment orders
You can now access assigned fulfillment orders from the assignedFulfillmentOrders connection on the QueryRoot object instead of from the pre-existing 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 enum also now includes the PICKUP_POINT value to identify fulfillment orders containing deliveries to pickup point locations.
Learn how to generate pickup point options.
Anchor to Fulfillment order line itemsFulfillment order line items
The 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.
Anchor to GraphQL completenessGraph QL completeness
We've added new types to the GraphQL Admin API to provide parity with the following REST resources: CarrierService, Customer, Fulfillment, FulfillmentEvent, FulfillmentService, InventoryItem, Location, Order, and 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 |
Anchor to Included fields on webhook subscriptionsIncluded fields on webhook subscriptions
The 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.
Anchor to Improvements to ShopPolicy objectImprovements to Shop Policy object
We've added new fields to the 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 |
Anchor to Improvements to Shopify Payments payouts and balance transactionsImprovements 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 to filter and sort payouts using the
sortKeyandsavedSearchIdparameters. This functionality allows you to efficiently search and organize payouts based on specific criteria such asledger_type,status,amount,currency, andissued_at. -
You can now use the following new fields on the
ShopifyPaymentsBalanceTransactionobject: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 thesourceTypeis an adjustment, then this value isnull.adjustmentOrderTransactions: An array of associated order transactions that resulted in the balance transaction. If thesourceTypeis not an adjustment, then this array is null. Each object in the array includesadjustmentReason, which specifies the reason for the adjustment associated with the transaction. If thesourceTypeis not an adjustment, then value isnull.
Anchor to Inventory error codeInventory error code
The LEDGER_DOCUMENT_INVALID error code has been added to the inventorySetScheduledChanges mutation.
The error code is returned when the ledgerDocumentUri provided is not a valid URI.
Anchor to Inventory item dataInventory item data
Anchor to BreakingBreaking
Prior to API version 2024-07, you could send inventory item data using ProductVariant mutations or on the 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 is now the input object type on the inventoryItemUpdate mutation instead of the InventoryItemUpdateInput input object.
Anchor to Location objectLocation object
Anchor to BreakingBreaking
The 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.
Anchor to Marketing activity improvementsMarketing activity improvements
Anchor to BreakingBreaking
You can now use the urlParameterValue field as a tracking parameter in the marketingActivityCreateInput and marketingActivityUpdateInput input objects. This field is currently only available to select partners. Most partners should continue to use UTMs for tracking parameters.
Additionally, the MarketingActivityUserError enum is now a required type on the userError field for the marketingEngagementCreate mutation.
Anchor to Media included in product webhooksMedia included in product webhooks
The PRODUCTS_CREATE and PRODUCTS_UPDATE webhook payloads now contain information about the media on a product.
Anchor to Media referencesMedia references
You can now use the 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 |
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 |
Anchor to Metafield access controlsMetafield access controls
Anchor to BreakingBreaking
Apps can now query the access field of metafield definitions that they have access to but don't own. Previously, an AuthorizationError error was returned when accessing the field for metafield definitions that an app didn't have permissions to manage.
Querying the 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 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 input object now use dedicated input enum types, MetafieldAdminAccessInput and 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 |
Anchor to Metafield connections for OnlineStore objectsMetafield connections for Online Store objects
You can now use the metafields and metafieldDefinitions connections on the OnlineStoreArticle, OnlineStoreBlog, and OnlineStorePage objects. Previously, you could only retrieve metafields and metafield definitions connections using the REST Admin API.
Anchor to Metafield definitions and constraintsMetafield 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 |
Anchor to Metafield error codeMetafield error code
We've added a new error code for mutations that set metafields. The INTERNAL_ERROR error code has been added to the MetafieldsSetUserErrorCode enum.
Anchor to Metafield JSON valueMetafield JSON value
The Metafield and 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. 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.
Anchor to Metafields reserved namespacesMetafields reserved namespaces
We've added the RESERVED_NAMESPACE_ORPHANED_METAFIELDS error code to the MetafieldDefinitionDelete mutation.
Anchor to Missing payment information for subscriptionsMissing payment information for subscriptions
The MISSING_CUSTOMER_PAYMENT_METHOD error code is now returned when payment information is missing on the subscriptionDraftCommit mutation.
Anchor to MetaobjectsMetaobjects
We've added the DISPLAY_NAME_CONFLICT error code value to the MetaobjectUserErrorCode enum.
Anchor to Online store password protectionOnline store password protection
You can now retrieve information about the storefront password of an online store using the OnlineStorePasswordProtection and OnlineStore objects.
The variants and productOptions fields on the ProductSetInput input object are now optional. In API versions prior to 2024-07, the variants and productOptions fields were required.
Anchor to Order captureOrder 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 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.
Anchor to Order transactionsOrder transactions
You can now use the transactionsCount field on the Order object to return the number of transactions associated with a given order.
We've also added the 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.
Anchor to Product bundlesProduct bundles
We've added the 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
bundleComponentsfield on theDraftOrderBundleLineItemComponentInputinput object. - Add a bundle item to a draft order by including the
bundleComponentsfield on thedraftOrderLineItemInputinput object.
Additionally, the CartTransform function now automatically runs on all draft orders.
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 |
Anchor to Product feed variant imagesProduct feed variant images
Anchor to BreakingBreaking
As of API version 2024-07, the variant image field in the PRODUCT_FEEDS_INCREMENTAL_SYNC and PRODUCT_FEEDS_FULL_SYNC webhook subscription topics 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.
Anchor to Product options error codeProduct options error code
The LINKED_METAFIELD_DEFINITION_NOT_FOUND value has been added to the ProductOptionUpdateUserErrorCode enum.
Anchor to Promise provider dataPromise provider data
You can now use the sourceReference field on the DeliveryMethod object to return promise provider data associated with a delivery promise.
Anchor to Product queryProduct query
You can now use the published_at filter on the product query to determine the date and time when a product was published to the Online Store.
Anchor to Product taxonomyProduct taxonomy
Anchor to BreakingBreaking
The following types now have a category field, which accepts the global ID (GID) of a taxonomy category that's specified by a merchant:
ProductInputinput objectShopobjectMetafieldReferenceunion
We've also deprecated the allProductCategories field on the Shop object. Use the allProductCategoriesList field on the Shop object instead.
Anchor to Product translationsProduct translations
You can now use the includesTranslations field on the ProductDuplicateAsyncInput input object to specify whether to include translations when running the 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.
Anchor to Product variantsProduct variants
Anchor to BreakingBreaking
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.
Anchor to Querying media in filesQuerying media in files
You can now use the 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 |
Anchor to Removals of types and fieldsRemovals of types and fields
Anchor to BreakingBreaking
We've removed the following types and fields from the GraphQL Admin API:
| Name | Type | Change |
|---|---|---|
ShippingLabel | Object | Removed. |
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. Non-product based fulfillment services are no longer supported. |
Anchor to Retail locationsRetail locations
You can now use the retailLocation field on the Order object to query the physical location where a retail order is created or completed.
Anchor to Refund line itemsRefund line items
You can now use the id field on the RefundLineItem object to return the global ID of the specified refund line item object.
Anchor to RefundsRefunds
Anchor to BreakingBreaking
Shopify's suggestion for a refund is now inclusive of payable charges, such as exchange items and fees, alongside returns.
The Return.suggestedRefund query and 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.
Anchor to ReturnsReturns
As of API version 2024-07, the Return.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:
Anchor to Selling plansSelling plans
Metafields are now supported on the 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 |
Anchor to Set metafields using compare-and-swap (CAS)Set metafields using compare-and-swap (CAS)
You can now set metafields using compare-and-swap (CAS) with the compareDigest field on the metafieldsSet mutation. By using CAS, you can properly handle concurrency requests.
Anchor to Shopify mobile appsShopify mobile apps
As of API version 2024-07, we're introducing a new 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 |
Anchor to Shopify Payments balance transactionsShopify 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 |
Anchor to ShopifyQLShopify QL
Anchor to BreakingBreaking
We've deprecated the shopifyqlQuery query. Use the GraphQL Admin API instead to extract data for your use cases.
Anchor to Sorting customersSorting customers
Anchor to BreakingBreaking
The following CustomerSortKeys are now deprecated:
LAST_ORDER_DATEORDERS_COUNTTOTAL_SPENT
You can order customers by these attributes if you filter customers using segments.
Anchor to Store credit at checkoutStore credit at checkout
You can now use the StoreCreditAccount object to retrieve information about the monetary balance that can be redeemed at checkout for purchases in the store.
Anchor to Synchronous input improvement for productSet mutationSynchronous input improvement for product Set mutation
Anchor to BreakingBreaking
The 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.
Anchor to Tax collection improvementsTax collection improvements
We've added 14 additional LocalizationExtensionsKey values to support the collection of tax and shipping credentials in several new countries.
Anchor to Translatable content typesTranslatable content types
You can now use the following metafield definition types to save link-related content:
Anchor to Validation status for shipping addressesValidation status for shipping addresses
You can now use the 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.
Anchor to Webhook sub-topicsWebhook sub-topics
Anchor to BreakingBreaking
The subTopic field has been removed from the WebhookSubscription object. Use the filter field instead.
Anchor to Webhook topicsWebhook 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 |
Anchor to REST Admin API changesREST Admin API changes
Version 2024-07 of the REST Admin API introduces the following changes:
Anchor to Adjustment reason for Shopify Payments transactionsAdjustment reason for Shopify Payments transactions
The Shopify Payments Transactions resource now returns the adjustment_reason property to describe the reason an adjustment was made.
Anchor to Deprecation of REST resourcesDeprecation of REST resources
Anchor to BreakingBreaking
The Checkout resource is now deprecated. For more information, refer to the Developer changelog.
We've also deprecated all endpoints on the Country and Province resources. For a complete list of affected endpoints, and the GraphQL type equivalents to use instead, refer to the Developer changelog.
Anchor to New properties on the FulfillmentOrder resourceNew properties on the Fulfillment Order resource
The following properties have been added to delivery_method property on the 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.
Anchor to Order editingOrder editing
The 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.
Anchor to Storefront API changesStorefront API changes
Version 2024-07 of the Storefront API introduces the following changes:
Anchor to Cart billing addressCart billing address
You can now use the cartBillingAddressUpdate mutation to associate a billing address with a cart.
Anchor to Cart error codeCart error code
The NOTE_TOO_LONG error code is now returned in cart mutations when a note exceeds the maximum limit of 5000 characters.
Anchor to Cart wallet preferencesCart wallet preferences
Anchor to BreakingBreaking
We've deprecated the following types:
-
walletPreferencesargument on theCartBuyerIdentityInputinput object -
walletPreferencesfield on theCartBuyerIdentityobjectUse
CartBuyerIdentityInput.preferences.walletinstead.
Anchor to Checkout types removedCheckout types removed
Anchor to BreakingBreaking
We've removed checkout types from the Storefront API, following their deprecation in the 2024-04 API version.
For more information, refer to the developer changelog.
Anchor to Discount computationsDiscount computations
We've added the targetType field to the CartDiscountAllocation interface. The targetType field ensures comprehensive discount calculations, which are crucial for payment integrations.
Anchor to Gift cardsGift cards
You can now manage gift cards on a cart in the following ways:
-
When creating a cart: Add the
giftCardCodesfield to theCartInputinput object. -
After a cart is created: Run the
cartGiftCardCodesUpdatemutation. -
Querying for applied gift cards: Use the
appliedGiftCardsfield.The following new types are available:
New types for managing gift cards on a cart Name Type Change cartGiftCardCodesUpdateMutation Added giftCardCodesField Added to CartInputappliedGiftCardsField Added to Cartobject
Anchor to Removals of types and fieldsRemovals of types and fields
Anchor to BreakingBreaking
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. |
Anchor to Shop Pay payment request checkoutsShop 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 |
Anchor to Single-use delivery addressesSingle-use delivery addresses
Carts now support single-use delivery addresses with the oneTimeUse field on the 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.
Anchor to Shopify Function APIs changesShopify Function APIs changes
Version 2024-07 of the Shopify Function APIs introduces the following changes:
Anchor to Metafields support on selling plansMetafields support on selling plans
The HasMetafields interface is now available on the SellingPlan object associated with each Function API.
Anchor to Order Routing Location Rule APIOrder Routing Location Rule API
We've added the lines field to the FulfillmentGroup object. The lines field returns a list of cart lines containing information about the items that are part of the fulfillment group.
Anchor to Payment Customization APIPayment Customization API
API clients installed on Shopify Plus stores can now make use of the optional placements 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.
Anchor to Payment method namesPayment method names
Anchor to BreakingBreaking
Previously, the PaymentCustomizationPaymentMethod 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" |
Anchor to Product Discount APIProduct Discount API
The Product Discount API now supports 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.
Anchor to Customer Account API changesCustomer Account API changes
Version 2024-07 of the Customer Account API introduces the following changes:
Anchor to Financial status of an orderFinancial status of an order
You can now determine whether the financial status of an order is expired using the EXPIRED value on the OrderFinancialStatus enum.
Anchor to Set metafields using compare-and-swap (CAS)Set metafields using compare-and-swap (CAS)
You can now set metafields using compare-and-swap (CAS) with the compareDigest field on the metafieldsSet mutation. By using CAS, you can properly handle concurrency requests.
Anchor to Store credit at checkoutStore credit at checkout
Customers who are authenticated with a customer account can now review and spend their store credit at checkout.
Anchor to Writing metafield valuesWriting metafield values
Anchor to BreakingBreaking
You can now use the metafieldsSet mutation to assign metafield values on Customer, Order, Company, and 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 will not be available to the Customer Account API.