2024-07 release notes (Release candidate)
Release date | Date version is no longer supported |
---|---|
July 1, 2024 | July 1, 2025 |
What's new in 2024-07
The 2024-07 version of Shopify's APIs include the following highlights:
- 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.
- Use the
promoteMarketToPrimary
mutation to update a market to become the primary market. - The
PRODUCTS_CREATE
andPRODUCTS_UPDATE
webhook payloads now contain information about the media on a product. - Use the
metafields
andmetafieldDefinitions
connections on theOnlineStoreArticle
,OnlineStoreBlog
, andOnlineStorePage
objects. Metafields are also now supported on theSellingPlan
object. - Use the
files
query to retrieve 3D models and external videos. - The
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.
Breaking changes
Anchor link to section titled "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.
Deprecation of REST Checkout
resource
Anchor link to section titled "Deprecation of REST Checkout resource"The Checkout
resource is deprecated. For more information, refer to the Developer changelog.
Inventory item data
Anchor link to section titled "Inventory 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.
Metafield access controls
Anchor link to section titled "Metafield 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.
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 |
Product feed variant images
Anchor link to section titled "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 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.
Removals of types and fields
Anchor link to section titled "Removals 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. |
GraphQL Admin API changes
Anchor link to section titled "GraphQL Admin API changes"The following changes are introduced in the 2024-07 version of the GraphQL Admin API.
Cash 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.
Checkout 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 |
Delivery 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.
Discounts
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 |
Fulfillment orders
The DeliveryMethodType
enum now includes the PICKUP_POINT
value to identify fulfillment orders containing deliveries to pickup point locations.
GraphQL completeness
We've added new types to the GraphQL Admin API to provide parity with equivalent REST resources: CarrierService
, Fulfillment
, FulfillmentEvent
, FulfillmentService
, and Location
.
The following new types are available:
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 |
fulfillmentsCount |
Field | Added to Order object |
createdAt |
Field | Added to FulfillmentEvent object |
trackingSupport |
Field | Added to FulfillmentService object |
locationsCount |
Query | Added |
Included 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.
Improvements to ShopPolicy 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 |
Inventory 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.
Markets
Use the promoteMarketToPrimary
mutation to update a market to become the primary market.
After running the promoteMarketToPrimary
mutation, the previous primary market becomes a non-primary market. The previous primary market's web presences are moved to the new primary market. If the market that's being promoted had its own dedicated domain before you ran the mutation, then that domain is disconnected so that the primary domain can be connected. Any traffic going to disconnected domains is redirected to the store's primary domain.
The promoteMarketToPrimary
mutation has the following limitations:
- It can't be used on markets that are using subfolder web presences. For example,
/en-ca
. This is due to the existing limitation of primary markets not supporting subfolder web presences. - It can't be used on markets that contain multiple countries. For example, Europe. This is due to the existing limitation that primary markets can't be multi-country.
- The market must be active.
Media included in product webhooks
The PRODUCTS_CREATE
and PRODUCTS_UPDATE
webhook payloads now contain information about the media on a product.
Media 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 |
Metafield 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.
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 |
Metafield connections for OnlineStore 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.
Metafields reserved namespaces
We've added the RESERVED_NAMESPACE_ORPHANED_METAFIELDS
error code to the MetafieldDefinitionDelete
mutation.
Missing payment information for subscriptions
The MISSING_CUSTOMER_PAYMENT_METHOD
error code is now returned when payment information is missing on the subscriptionDraftCommit
mutation.
Metaobjects
We've added the DISPLAY_NAME_CONFLICT
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
and OnlineStore
objects.
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
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
.
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 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
value has been added to the ProductOptionUpdateUserErrorCode
enum.
Promise provider data
You can now use the sourceReference
field on the DeliveryMethod
object to return promise provider data associated with a delivery promise.
Product 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
bundleComponents
field on theDraftOrderBundleLineItemComponentInput
input object. - Add a bundle item to a draft order by including the
bundleComponents
field on thedraftOrderLineItemInput
input object.
Additionally, the CartTransform
function now automatically runs on all draft orders.
Product 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.
Querying 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 |
Removals 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. |
Retail 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.
Returns
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:
Selling 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 |
Shopify 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 |
Shopify Payments balance transactions
You can now query the following new types related to 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 |
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
Anchor link to section titled "REST Admin API changes"The following changes are introduced in the 2024-07 version of the REST Admin API.
Adjustment reason for Shopify Payments transactions
The Shopify Payments Transactions
resource now returns the adjustment_reason
property to describe the reason an adjustment was made.
Deprecation of Checkout resource
The Checkout
resource is deprecated. For more information, refer to the Developer changelog.
Order 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.
Storefront API changes
Anchor link to section titled "Storefront API changes"The following changes are introduced in the 2024-07 version of the Storefront API.
Gift cards
You can now manage gift cards on a cart in the following ways:
- When creating a cart: Add the
giftCardCodes
field to theCartInput
input object. - After a cart is created: Run the
cartGiftCardCodesUpdate
mutation. - Querying for applied gift cards: Use the
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 |
Shopify Function APIs changes
Anchor link to section titled "Shopify Function APIs changes"The following changes are introduced in the 2024-07 version of Shopify Function APIs.
Metafields support on selling plans
The HasMetafields
interface is now available on the SellingPlan
object associated with each Function API.
Customer Account API changes
Anchor link to section titled "Customer Account API changes"The following changes are introduced in the 2024-07 version of the Customer Account API.
Financial 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.