> 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.
<table>
<caption>The API version release date and the date that the version is no longer supported</caption>
<thead>
<tr>
<th scope="col">Release date</th>
<th scope="col">Date version is no longer supported</th>
</tr>
</thead>
<tbody>
<tr>
<td scope="row">January 1, 2024</td>
<td scope="row">January 1, 2025</td>
</tr>
</tbody>
</table>
**What's new in 2024-01**
The 2024-01 version of Shopify's APIs include the following highlights:
- [Buy X Get Y discounts](/docs/apps/build/discounts#related-mutations-and-queries) now support setting a fixed amount discount.
- The new [`orderCancel`](/docs/api/admin-graphql/2024-01/mutations/orderCancel) mutation enables you to cancel orders.
- You can now [schedule changes to inventory quantities](/docs/apps/build/orders-fulfillment/inventory-management-apps/manage-quantities-states#schedule-changes-to-inventory-quantities).
- More granular capabilities are available for separating and combining line items inside a [fulfillment order](/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder).
- You can now update and remove discounts when [editing orders](/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders#add-a-discount-to-the-variant).
- [Various improvements](#graphql-admin-api-changes) have been made to subscription contracts, subscription billing attempts, metaobjects, metafield definitions, and marketing activities.
- [Webhook sub-topics](/docs/apps/build/webhooks/customize/sub-topics) enable the delivery of a more specific and relevant stream of webhooks to your app.
- [New types](#payments-apps-api-changes) enable some credit card [payment apps](/docs/apps/build/payments) to support vaulting card data in Shopify.
- Several improvements have been made to [Shopify Function APIs](#shopify-function-apis-changes).
- The new [Customer Account API](/docs/api/customer) offers a secure and private way of accessing private customer-scoped data.
## 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.
### Change to AppSubscriptionDiscountInput
The [`durationLimitInIntervals`](/docs/api/admin-graphql/2024-01/input-objects/AppSubscriptionDiscountInput#field-appsubscriptiondiscountinput-durationlimitinintervals) field on the `AppSubscriptionDiscountInput` input object no longer accepts `0` as a value.
To create a discount with an unlimited duration, don't specify the `durationLimitInIntervals` field.
### Field deprecation on ProductInput
We've deprecated the [`images` field on the `ProductInput` input object](/docs/api/admin-graphql/2024-01/input-objects/ProductInput#field-productinput-images).
Use the `media` argument on the [`productCreate`](/docs/api/admin-graphql/2023-10/mutations/productcreate#argument-media) and [`productUpdate`](/docs/api/admin-graphql/2023-10/mutations/productupdate#argument-media) mutations instead.
### Field removals on ProductVariantInput
We've removed the deprecated `imageId` and `imageSrc` fields from the [`ProductVariantInput`](/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput) input object.
Use the [`mediaId`](/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput#field-productvariantinput-mediaid) and [`mediaSrc`](/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput#field-productvariantinput-mediasrc) fields instead.
### Field removal on the Shipping Discount Function API
We've removed the deprecated `discountApplicationStrategy` field on the [`FunctionRunResult`](/docs/api/functions/reference/shipping-discounts/graphql/functionrunresult?api%5Bversion%5D=latest) object, and its predecessor, the [`FunctionResult`](/docs/api/functions/reference/shipping-discounts/graphql/functionresult?api%5Bversion%5D=latest) object.
The discount application strategy for shipping discount functions is always considered to be `ALL`. This means that all applicable discounts are returned by a shipping discount function.
### Handle as a scalar type on Shopify Function APIs
The following fields and arguments that return a handle to identify a [Function](/docs/apps/build/functions) resource now use the appropriate `Handle` scalar as their type:
<table>
<caption>Fields and arguments that use <code>Handle</code> as a scalar type</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>CartDeliveryOption</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>Product</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>MoveOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/moveoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>RenameOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/renameoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>HideOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/hideoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>GateConfiguration</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Argument</td>
<td>On the <code>HasGates</code> interface for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>Market</code> object for all Function APIs</td>
</tr>
</table>
### Marketing activities
The following breaking changes have been made to marketing activity types on the GraphQL Admin API:
- The `channel` field on the [`marketingActivityCreateExternal`](/docs/api/admin-graphql/2024-01/mutations/marketingActivityCreateExternal) and [`marketingActivityUpdateExternal`](/docs/api/admin-graphql/2024-01/mutations/marketingActivityUpdateExternal) mutations has been renamed to `marketingChannelType`.
- `utcOffset` and `isCumulative` are now required fields on the [`marketingEngagementInput`](/docs/api/admin-graphql/2024-01/input-objects/MarketingEngagementInput) input object.
- The `fetchedAt` field has been removed from the [`marketingEngagementInput`](/docs/api/admin-graphql/2024-01/input-objects/MarketingEngagementInput) input object.
- The `utm` field has been deprecated from the [`MarketingActivityUpdateExternalInput`](/docs/api/admin-graphql/2024-01/input-objects/MarketingActivityUpdateExternalInput) input object.
### Marketing fields and properties removals
- **GraphQL Admin API**: We've removed the following deprecated fields on the [`Customer`](/docs/api/admin-graphql/2024-01/objects/Customer) object and [`CustomerInput`](/docs/api/admin-graphql/2024-01/input-objects/CustomerInput) input object:
- `acceptsMarketing`
- `acceptsMarketingUpdatedAt`
- `MarketingOptInLevel`
Use the [`emailMarketingConsent`](/docs/api/admin-graphql/2024-01/objects/Customer#field-customer-emailmarketingconsent) field instead.
- **REST Admin API**: We've removed the following deprecated properties on the [`Order`](/docs/api/admin-rest/2024-01/resources/order) and [`Customer`](/docs/api/admin-rest/2024-01/resources/customer) resources:
- `accepts_marketing`
- `accepts_marketing_updated_at`
- `marketing_opt_in_level`
Use the [`email_marketing_consent`](/docs/api/admin-rest/2024-01/resources/customer#resource-object) property instead.
### Subscription billing attempts
The [`SubscriptionBillingAttemptCreate`](/docs/api/admin-graphql/2024-01/mutations/subscriptionBillingAttemptCreate) mutation now prevents the creation of billing attempts if a subscription contract has one of the following terminal statuses:
- `EXPIRED`
- `CANCELLED`
- `STALE`
We've also added the [`CONTRACT_TERMINATED`](/docs/api/admin-graphql/2024-01/enums/BillingAttemptUserErrorCode#value-contractterminated) error code to the `BillingAttemptUserErrorCode` enum. This new error code is returned in the case where billing attempt creation is prevented.
[Learn how to schedule and automate the billing of subscriptions](/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt).
### Subscription contracts
The `STALE` value on the [`SubscriptionContractSubscriptionStatus`](/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus) enum has been removed. Existing subscription contracts with the `STALE` status will be returned as `CANCELLED`, and you won't be able to update the status of a subscription contract to `STALE`.
Use the [`EXPIRED`](/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus#value-expired) or [`CANCELLED`](/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus#value-cancelled) values instead.
## GraphQL Admin API changes
The following are all the changes currently introduced in the 2024-01 version of the GraphQL Admin API.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Abandoned checkouts</h3>
</div>
<div class="accordion-content">
<p>You can now query a single line item in an abandoned checkout by using the <a href="/docs/api/admin-graphql/2024-01/objects/AbandonedCheckoutLineItem"><code class="text-highlight text-highlight--grey">AbandonedCheckoutLineItem</code></a> object. The <a href="/docs/api/admin-graphql/2024-01/objects/AbandonedCheckoutLineItem#field-abandonedcheckoutlineitem-title"><code class="text-highlight text-highlight--grey">title</code></a> field on the <code class="text-highlight text-highlight--grey">AbandonedCheckoutLineItem</code> object, which defaults to the product title, can now also accept a <code class="text-highlight text-highlight--grey">null</code> value.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>App subscription discounts <span id="durationLimitInIntervals-field" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/admin-graphql/2024-01/input-objects/AppSubscriptionDiscountInput#field-appsubscriptiondiscountinput-durationlimitinintervals"><code class="text-highlight text-highlight--grey">durationLimitInIntervals</code></a> field on the <code class="text-highlight text-highlight--grey">AppSubscriptionDiscountInput</code> input object no longer accepts <code class="text-highlight text-highlight--grey">0</code> as a value.</p>
<p>To create a discount with an unlimited duration, don't specify the <code class="text-highlight text-highlight--grey">durationLimitInIntervals</code> field.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Buy X Get Y discounts</h3>
</div>
<div class="accordion-content">
<p>Buy X Get Y discounts now support setting a fixed amount discount. You can use this option alongside the existing percentage or free item discount options for a minimum qualifying purchase.</p>
<p>For example, you can set a fixed amount discount to create promotions such as "Buy 2 items, get $20 off". Fixed amount discounts can be set for an automatic discount or a discount code using the <a href="/docs/api/admin-graphql/2024-01/unions/DiscountEffect">GraphQL Admin API</a>.</p>
<p><a href="/docs/apps/build/discounts#related-mutations-and-queries">Learn how to create and manage different types of discounts</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Cancelling orders</h3>
</div>
<div class="accordion-content">
<p>You can now use the <a href="/docs/api/admin-graphql/2024-01/mutations/orderCancel"><code class="text-highlight text-highlight--grey">orderCancel</code></a> mutation to cancel an order. The mutation enables apps to specify some options for cancellation, a reason for cancellation, and a merchant-facing staff note. For example, options for cancellation might include whether to refund a customer, restock inventory quantities, or notify a customer.</p>
<p>The mutation performs cancellation asynchronously in a background job and returns a <a href="/docs/api/admin-graphql/2024-01/objects/Job"><code class="text-highlight text-highlight--grey">Job</code></a> object that you can <a href="/docs/api/admin-graphql/2024-01/queries/job">query</a> to poll for the cancellation status.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for cancelling orders</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/orderCancel">orderCancel</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/OrderCancelUserError">OrderCancelUserError</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Capturing transactions multiple times</h3>
</div>
<div class="accordion-content">
<p>You can now use the <a href="/docs/api/admin-graphql/2024-01/objects/OrderTransaction#field-ordertransaction-multicapturable"><code class="text-highlight text-highlight--grey">multiCapturable</code> field on the <code class="text-highlight text-highlight--grey">OrderTransaction</code> object</a> to determine whether a transaction can be captured multiple times.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Cart and checkout operations</h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/admin-graphql/2024-01/mutations/cartTransformCreate"><code class="text-highlight text-highlight--grey">CartTransformCreate</code></a> mutation now supports a <code class="text-highlight text-highlight--grey">blockOnFailure</code> argument that determines if cart and checkout operations should be blocked if a <a href="/docs/apps/build/product-merchandising/bundles/add-customized-bundle-function">Cart Transform function</a> fails to run. This mutation can be used as a safeguard if the Cart Transform function is considered a critical component in resolving merchandise attributes, such price, title, or image.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for cart and checkout operations</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/cartTransformCreate#argument-blockonfailure">blockOnFailure</a></code></td>
<td>Argument</td>
<td>Added to the <code>CartTransformCreate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/CartTransform#field-carttransform-blockonfailure">blockOnFailure</a></code></td>
<td>Field</td>
<td>Added to the <code>CartTransform</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Checkout branding</h3>
</div>
<div class="accordion-content">
<p>You can now use the <a href="/docs/api/admin-graphql/2024-01/mutations/checkoutBrandingUpsert"><code class="text-highlight text-highlight--grey">checkoutBrandingUpsert</code></a> mutation to reset branding settings to their default state without resetting each field explicitly. You can pass a <code class="text-highlight text-highlight--grey">null</code> value to the <a href="/docs/api/admin-graphql/2024-01/mutations/checkoutBrandingUpsert#argument-checkoutbrandinginput"><code class="text-highlight text-highlight--grey">checkoutBrandingInput</code></a> argument to clear all of the branding settings, which will revert the branding of the checkout to its default state.</p>
<p>You can also use the GraphQL Admin API to customize the look of the <code class="text-highlight text-highlight--grey">ChoiceList</code> components in checkout.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for checkout branding</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/checkoutBrandingUpsert">checkoutBrandingUpsert</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/CheckoutBrandingCustomizationsInput#field-checkoutbrandingcustomizationsinput-choicelist">choiceList</a></code></td>
<td>Field</td>
<td>Added to the <code>CheckoutBrandingCustomizationsInput</code> input object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/CheckoutBrandingCustomizations#field-checkoutbrandingcustomizations-choicelist">choiceList</a></code></td>
<td>Field</td>
<td>Added to the <code>CheckoutBrandingCustomizations</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Customer data erasure</h3>
</div>
<div class="accordion-content">
<p>You can now use the GraphQL Admin API to enable merchants to handle customer data erasure requests in compliance with General Data Protection Regulation (GDPR), California Consumer Privacy Act (CCPA), and other data protection regulations.</p>
<p>To learn more about how data erasure is processed and the impact on customer data, refer to <a rel="external noreferrer noopener" target="_blank" href="https://help.shopify.com/manual/privacy-and-security/privacy/processing-customer-data-requests#erase-customer-personal-data">Processing customer data requests</a>.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for customer data erasure</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/customerRequestDataErasure">customerRequestDataErasure</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/customerCancelDataErasure">customerCancelDataErasure</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/CustomerRequestDataErasureUserError">CustomerRequestDataErasureUserError</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/CustomerCancelDataErasureUserError">CustomerCancelDataErasureUserError</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Deleting market regions</h3>
</div>
<div class="accordion-content">
<p>You can now use the <a href="/docs/api/admin-graphql/2024-01/mutations/marketRegionsDelete"><code class="text-highlight text-highlight--grey">marketRegionsDelete</code></a> mutation to delete a list of market regions.</p>
<p><a href="/docs/apps/build/markets">Learn more about Shopify Markets</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Filtering prices</h3>
</div>
<div class="accordion-content">
<p>You can now use a new <code class="text-highlight text-highlight--grey">query</code> parameter on the <a href="/docs/api/admin-graphql/2024-01/objects/PriceList#connection-pricelist-prices"><code class="text-highlight text-highlight--grey">prices</code> connection of the <code class="text-highlight text-highlight--grey">PriceList</code> object</a> to filter prices for each product or product variant ID.</p>
<p>For example, <code class="text-highlight text-highlight--grey">prices(first: 10, query: "product_id:1")</code> filters the first ten prices of a product with an ID of <code class="text-highlight text-highlight--grey">gid://shopify/Product/1</code>.</p>
<p>Similarly, <code class="text-highlight text-highlight--grey">prices(first: 10, query: "variant_id:1")</code> filters the first ten prices for a product variant with an ID of <code class="text-highlight text-highlight--grey">gid://shopify/ProductVariant/1</code>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Financial summaries</h3>
</div>
<div class="accordion-content">
<p>You can now use the <code class="text-highlight text-highlight--grey">financialSummaries</code> field on the <a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLineItem"><code class="text-highlight text-highlight--grey">FulfillmentOrderLineItem</code></a> object to retrieve the financial summary of a fulfillment order's line items.</p>
<p>With this change, order information that's required to calculate the financial specifics of an order is accessible using the <code class="text-highlight text-highlight--grey">fulfillmentOrder.lineItems</code> connection and any of the <code class="text-highlight text-highlight--grey">fulfillment_orders</code> access scopes. The same data is available using <code class="text-highlight text-highlight--grey">fulfillmentOrder.order.lineItems</code>, but requires the <code class="text-highlight text-highlight--grey">read_orders</code> access scope.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for financial summaries</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLineItemFinancialSummary">FulfillmentOrderLineItemFinancialSummary</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FinancialSummaryDiscountAllocation">FinancialSummaryDiscountAllocation</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FinancialSummaryDiscountApplication">FinancialSummaryDiscountApplication</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLineItem#field-fulfillmentorderlineitem-financialsummaries">financialSummaries</a></code></td>
<td>Field</td>
<td>Added to the <code>FulfillmentOrderLineItem</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Fulfillment hold reasons</h3>
</div>
<div class="accordion-content">
<p>A new fulfillment hold reason (<a href="/docs/api/admin-graphql/2024-01/enums/FulfillmentHoldReason#value-awaitingreturnitems"><code class="text-highlight text-highlight--grey">AWAITING_RETURN_ITEMS</code></a>) is now applied to a <a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentHold">fulfillment hold</a> on a fulfillment order when a return is created with exchange items.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Including translations when duplicating products</h3>
</div>
<div class="accordion-content">
<p>You can now specify whether to include translations when you run the <a href="/docs/api/admin-graphql/2024-01/mutations/productDuplicate"><code class="text-highlight text-highlight--grey">productDuplicate</code></a> mutation. If you specify the optional <code class="text-highlight text-highlight--grey">includeTranslations</code> argument as <code class="text-highlight text-highlight--grey">true</code>, then all translations that are saved on the product and its associated variants and metafields are copied over to the new product.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Localizing metaobjects for different markets</h3>
</div>
<div class="accordion-content">
<p>Metaobjects are now exposed as a value on the <a href="/docs/api/admin-graphql/2024-01/enums/MarketLocalizableResourceType#value-metaobject"><code class="text-highlight text-highlight--grey">MarketLocalizableResourceType</code></a> enum. This means that metaobjects with a translatable capability are eligible for custom content by market through the GraphQL Admin API as well as the <a rel="external noreferrer noopener" target="_blank" href="https://apps.shopify.com/translate-and-adapt">Translate and Adapt</a> app. Localizable fields are determined by the metaobject type.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Marketing activities: Field changes <span id="marketing-activities" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>The following breaking changes have been made to marketing activity types:</p>
<ul>
<li><p>The <code class="text-highlight text-highlight--grey">channel</code> field on the <a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivityCreateExternal"><code class="text-highlight text-highlight--grey">marketingActivityCreateExternal</code></a> and <a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivityUpdateExternal"><code class="text-highlight text-highlight--grey">marketingActivityUpdateExternal</code></a> mutations has been renamed to <code class="text-highlight text-highlight--grey">marketingChannelType</code>.</p></li>
<li><p><code class="text-highlight text-highlight--grey">utcOffset</code> and <code class="text-highlight text-highlight--grey">isCumulative</code> are now required fields on the <a href="/docs/api/admin-graphql/2024-01/input-objects/MarketingEngagementInput"><code class="text-highlight text-highlight--grey">marketingEngagementInput</code></a> input object.</p></li>
<li><p>The <code class="text-highlight text-highlight--grey">fetchedAt</code> field has been removed from the <a href="/docs/api/admin-graphql/2024-01/input-objects/MarketingEngagementInput"><code class="text-highlight text-highlight--grey">marketingEngagementInput</code></a> input object.</p></li>
<li><p>The <code class="text-highlight text-highlight--grey">utm</code> field has been deprecated from the <a href="/docs/api/admin-graphql/2024-01/input-objects/MarketingActivityUpdateExternalInput"><code class="text-highlight text-highlight--grey">MarketingActivityUpdateExternalInput</code></a> input object.</p></li>
</ul>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Marketing activites: Improvements</h3>
</div>
<div class="accordion-content">
<p>We've made improvements to creating marketing activities, syncing aggregate marketing activity data, and deleting marketing activities.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for marketing activities</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivityUpsertExternal">marketingActivityUpsertExternal</a></code></td>
<td>Mutation</td>
<td>Added. Used to sync externally managed activities without having to keep track of Shopify IDs. <a href="/docs/api/usage/bulk-operations/imports">Bulk mutation support</a> has also been added to this mutation.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivityCreateExternal">marketingActivityCreateExternal</a></code></td>
<td>Mutation</td>
<td>Added. Used to create a hierarchy of activities. Activities can be created to represent ads, ad groups, or campaigns.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivityDeleteExternal">marketingActivityDeleteExternal</a></code></td>
<td>Mutation</td>
<td>Added. Used to delete a single external marketing activity.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingActivitiesDeleteAllExternal">marketingActivitiesDeleteAllExternal</a></code></td>
<td>Mutation</td>
<td>Added. Used to enqueue a job to bulk delete all external marketing activities and cleanup data if a store owner revokes permission to sync data to Shopify.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingEngagementCreate#argument-remoteid">remoteId</a></code></td>
<td>Field</td>
<td>Added. Used to reference a marketing activity in the <a href="/docs/api/admin-graphql/2024-01/mutations/marketingEngagementCreate">marketingEngagementCreate</a> mutation.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingEngagementCreate">marketingEngagementCreate</a></code></td>
<td>Mutation</td>
<td>Added. Used to sync aggregate data at the activity level and at the channel level. <a href="/docs/api/usage/bulk-operations/imports">Bulk mutation support</a> has also been added to this mutation.</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/marketingEngagementsDelete">marketingEngagementsDelete</a></code></td>
<td>Mutation</td>
<td>Added. Used to enqueue a job to delete all channel-level data that was sent through the <a href="/docs/api/admin-graphql/2024-01/mutations/marketingEngagementCreate">marketingEngagementCreate</a> mutation and cleanup data if a store owner revokes permission to sync data to Shopify.</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Marketing fields <span id="marketing-fields" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>We've removed the following deprecated fields on the <a href="/docs/api/admin-graphql/2024-01/objects/Customer"><code class="text-highlight text-highlight--grey">Customer</code></a> object and <a href="/docs/api/admin-graphql/2024-01/input-objects/CustomerInput"><code class="text-highlight text-highlight--grey">CustomerInput</code></a> input object:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">acceptsMarketing</code></li>
<li><code class="text-highlight text-highlight--grey">acceptsMarketingUpdatedAt</code></li>
<li><code class="text-highlight text-highlight--grey">MarketingOptInLevel</code></li>
</ul>
<p>Use the <a href="/docs/api/admin-graphql/2024-01/objects/Customer#field-customer-emailmarketingconsent"><code class="text-highlight text-highlight--grey">emailMarketingConsent</code></a> field instead.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Metaobjects and metaobject definitions</h3>
</div>
<div class="accordion-content">
<p>We've added new fields so that you can query for the user or app that created a metaobject or metaobject definition.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New fulfillment order webhook topics</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetaobjectDefinition">createdByApp</a></code></td>
<td>Field</td>
<td>Added to the <code>MetaobjectDefinition</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetaobjectDefinition">createdByStaff</a></code></td>
<td>Field</td>
<td>Added to the <code>MetaobjectDefinition</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/Metaobject">createdByApp</a></code></td>
<td>Field</td>
<td>Added to the <code>Metaobject</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/Metaobject">createdByStaff</a></code></td>
<td>Field</td>
<td>Added to the <code>Metaobject</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>New metafields error code</h3>
</div>
<div class="accordion-content">
<p>We've added the <code class="text-highlight text-highlight--grey">CAPABILITY_VIOLATION</code> error code to the <a href="/docs/api/storefront/2024-01/enums/MetafieldsSetUserErrorCode"><code class="text-highlight text-highlight--grey">MetafieldsSetUserErrorCode</code></a> enum. The error code is returned if you attempt to update a metafield in a way that doesn't conform to the enabled capabilities.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Order editing</h3>
</div>
<div class="accordion-content">
<p>You can now update and remove discounts when editing orders. To learn more about using discounts with order edits, refer to <a href="/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders#add-a-discount-to-the-variant">Edit an existing order</a>.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for order editing</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/orderEditUpdateDiscount">orderEditUpdateDiscount</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/orderEditRemoveDiscount">orderEditRemoveDiscount</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Order routing</h3>
</div>
<div class="accordion-content">
<p>The <code class="text-highlight text-highlight--grey">ORDER_ROUTING_LOCATION_RULE</code> value has been added to the <a href="/docs/api/admin-graphql/2024-01/enums/MetafieldOwnerType"><code class="text-highlight text-highlight--grey">MetafieldOwnerType</code></a> enum. To learn more about order routing, refer to <a href="/docs/apps/build/orders-fulfillment/order-routing-apps">Order routing apps</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Product images <span id="product-images" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>We've deprecated the <a href="/docs/api/admin-graphql/2024-01/input-objects/ProductInput#field-productinput-images"><code class="text-highlight text-highlight--grey">images</code> field on the <code class="text-highlight text-highlight--grey">ProductInput</code> input object</a>.</p>
<p>Use the <code class="text-highlight text-highlight--grey">media</code> argument on the <a href="/docs/api/admin-graphql/2023-10/mutations/productcreate#argument-media"><code class="text-highlight text-highlight--grey">productCreate</code></a> and <a href="/docs/api/admin-graphql/2023-10/mutations/productupdate#argument-media"><code class="text-highlight text-highlight--grey">productUpdate</code></a> mutations instead.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Product variant images <span id="product-variant-images" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>We've removed the deprecated <code class="text-highlight text-highlight--grey">imageId</code> and <code class="text-highlight text-highlight--grey">imageSrc</code> fields from the <a href="/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput"><code class="text-highlight text-highlight--grey">ProductVariantInput</code></a> input object.</p>
<p>Use the <a href="/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput#field-productvariantinput-mediaid"><code class="text-highlight text-highlight--grey">mediaId</code></a> and <a href="/docs/api/admin-graphql/2024-01/input-objects/ProductVariantInput#field-productvariantinput-mediasrc"><code class="text-highlight text-highlight--grey">mediaSrc</code></a> fields instead.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Retrieving payment details for transactions</h3>
</div>
<div class="accordion-content">
<p>You can now use the <code class="text-highlight text-highlight--grey">paymentDetails</code> field on the <a href="/docs/api/admin-graphql/2024-01/objects/SuggestedOrderTransaction"><code class="text-highlight text-highlight--grey">SuggestedOrderTransaction</code></a> object to retrieve payment details that are related to a transaction.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Scheduling changes to inventory quantities</h3>
</div>
<div class="accordion-content">
<p>You can now <a href="/docs/apps/build/orders-fulfillment/inventory-management-apps/manage-quantities-states#schedule-changes-to-inventory-quantities">schedule changes to inventory quantities</a> using the <a href="/docs/api/admin-graphql/2024-01/mutations/InventorySetScheduledChanges"><code class="text-highlight text-highlight--grey">InventorySetScheduledChanges</code></a> mutation.</p>
<p>For example, if an app user creates a purchase order and adds incoming quantities for a specified inventory item at a location, then they can also create a scheduled change that states the date that the quantities are expected to be transitioning from <code class="text-highlight text-highlight--grey">incoming</code> to <code class="text-highlight text-highlight--grey">available</code>. Information about scheduled changes to inventory quantities can help merchants make better buying or selling decisions.</p>
<aside class="note">
<h4>Note</h4>
<p>
The <a href="/docs/api/admin-graphql/2024-01/mutations/InventorySetScheduledChanges"><code class="text-highlight text-highlight--grey">InventorySetScheduledChanges</code></a> mutation won't automatically change inventory quantities. To change inventory quantities, you still need to use other inventory mutations, such as <a href="/docs/api/admin-graphql/2024-01/mutations/inventoryAdjustQuantities"><code class="text-highlight text-highlight--grey">InventoryAdjustQuantitites</code></a>, <a href="/docs/api/admin-graphql/2024-01/mutations/inventorySetQuantities"><code class="text-highlight text-highlight--grey">inventorySetQuantities</code></a>, or <a href="/docs/api/admin-graphql/2024-01/mutations/inventoryMoveQuantities"><code class="text-highlight text-highlight--grey">inventoryMoveQuantities</code></a>.</p>
</aside>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for scheduling changes to inventory quantities</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/InventorySetScheduledChanges">InventorySetScheduledChanges</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/InventoryScheduledChange">InventoryScheduledChange</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/InventoryScheduledChangeInput">InventoryScheduledChangeInput</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/InventoryScheduledChangeItemInput">InventoryScheduledChangeItemInput</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/InventorySetScheduledChangesInput">InventorySetScheduledChangesInput</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/InventoryLevel#connection-inventorylevel-scheduledchanges">scheduledChanges</a></code></td>
<td>Connection</td>
<td>Added to the <code>InventoryLevel</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/InventoryQuantity#field-inventoryquantity-id">id</a></code></td>
<td>Field</td>
<td>Added to the <code>InventoryQuantity</code> object. The <code>InventoryQuantity</code> object now implements a <code>Node</code> interface.</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Separating and combining fulfillment order line items</h3>
</div>
<div class="accordion-content">
<p>We've added more granular capabilities for separating and combining line items inside a <a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder">fulfillment order</a> so that you can partially fulfill an order or <a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLocationForMove">change the location</a> of specific line items.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for separating and combining fulfillment order line items</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder#connection-fulfillmentorder-locationsformove">lineItemIds</a></code></td>
<td>Argument</td>
<td>Added to the <code>locationsForMove</code> connection on the <code>FulfillmentOrder</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder#connection-fulfillmentorder-locationsformove">query</a></code></td>
<td>Argument</td>
<td>Added to the <code>locationsForMove</code> connection on the <code>FulfillmentOrder</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder#connection-fulfillmentorder-locationsformove">locationIds</a></code></td>
<td>Argument</td>
<td>Added to the <code>locationsForMove</code> connection on the <code>FulfillmentOrder</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrder#connection-fulfillmentorder-fulfillmentordersformerge">fulfillmentOrdersForMerge</a></code></td>
<td>Connection</td>
<td>Added to the <code>FulfillmentOrder</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLocationForMove#connection-fulfillmentorderlocationformove-availablelineitems">availableLineItems</a></code></td>
<td>Connection</td>
<td>Added to the <code>FulfillmentOrderLocationForMove</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLocationForMove#connection-fulfillmentorderlocationformove-unavailablelineitems">unavailableLineItems</a></code></td>
<td>Connection</td>
<td>Added to the <code>FulfillmentOrderLocationForMove</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLocationForMove#field-fulfillmentorderlocationformove-availablelineitemscount">availableLineItemsCount</a></code></td>
<td>Field</td>
<td>Added to the <code>FulfillmentOrderLocationForMove</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/FulfillmentOrderLocationForMove#field-fulfillmentorderlocationformove-unavailablelineitemscount">unavailableLineItemsCount</a></code></td>
<td>Field</td>
<td>Added to the <code>FulfillmentOrderLocationForMove</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/FulfillmentOrderSplitUserErrorCode#value-nolineitemsprovidedtosplit">NO_LINE_ITEMS_PROVIDED_TO_SPLIT</a></code></td>
<td>Field</td>
<td>Added to the <code>FulfillmentOrderSplitUserErrorCode</code> enum</td>
</tr>
</table>
<p><strong>New webhook topics</strong></p>
<p>The following new webhook topics are available:</p>
<table>
<caption>New fulfillment order webhook topics</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-fulfillmentorderssplit">FULFILLMENT_ORDERS_SPLIT</a></code></td>
<td>Value</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-fulfillmentordersmerged">FULFILLMENT_ORDERS_MERGED</a></code></td>
<td>Value</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Shopify Payments balance transactions</h3>
</div>
<div class="accordion-content">
<p>You can now use the GraphQL Admin API to query transactions that are associated with a <a rel="external noreferrer noopener" target="_blank" href="https://help.shopify.com/manual/payments/shopify-payments">Shopify Payments</a> account balance.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for Shopify Payments balance transactions</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/ShopifyPaymentsBalanceTransaction">ShopifyPaymentsBalanceTransaction</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/ShopifyPaymentsAccount#connection-shopifypaymentsaccount-balancetransactions">ShopifyPaymentsAccount.balanceTransactions</a></code></td>
<td>Connection</td>
<td>Added to the <code>ShopifyPaymentsAccount</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/SearchResultType#value-balancetransaction">BALANCE_TRANSACTION</a></code></td>
<td>Value</td>
<td>Added to the <code>SearchResultType</code> enum</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Storefront access controls for custom data</h3>
</div>
<div class="accordion-content">
<p>We've modified <a href="/docs/api/admin-graphql/2024-01/enums/MetafieldStorefrontAccess">storefront access controls</a> to be more explicit for <a href="/docs/apps/build/custom-data">custom data</a>. The changes affect how you can modify app reserved prefixes in the Shopify admin and how apps set access controls.</p>
<p>App reserved prefixes are configurable. For example, if you set access for <code class="text-highlight text-highlight--grey">admin</code> to be <code class="text-highlight text-highlight--grey">MERCHANT_READ</code> and <code class="text-highlight text-highlight--grey">storefront</code> to be <code class="text-highlight text-highlight--grey">PUBLIC_READ</code> then the merchant will have read-only access in the Shopify admin, and metafields will be publicly readable on storefront surface areas, including Liquid templates and the Storefront API.</p>
<p>Learn more about access controls for <a href="/docs/apps/build/custom-data/permissions">metafields</a> and <a href="/docs/apps/build/custom-data/permissions">metaobjects</a>.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for storefront access controls</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/MetafieldAccessInput#field-metafieldaccessinput-storefront">storefront</a></code></td>
<td>Field</td>
<td>Added to the <code>MetafieldAccessInput</code> input object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/MetafieldAccessUpdateInput#field-metafieldaccessupdateinput-storefront">storefront</a></code></td>
<td>Field</td>
<td>Added to the <code>MetafieldAccessUpdateInput</code> input object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetafieldAccess#field-metafieldaccess-storefront">storefront</a></code></td>
<td>Field</td>
<td>Added to the <code>MetafieldAccess</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/MetafieldDefinitionInput#field-metafielddefinitioninput-visibletostorefrontapi">visibleToStorefrontAPI</a></code></td>
<td>Field</td>
<td>Added to the <code>MetafieldDefinitionInput</code> input object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/input-objects/MetafieldDefinitionUpdateInput#field-metafielddefinitionupdateinput-visibletostorefrontapi">visibleToStorefrontAPI</a></code></td>
<td>Field</td>
<td>Added to the <code>MetafieldDefinitionUpdateInput</code> input object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetafieldDefinition#field-metafielddefinition-visibletostorefrontapi">visibleToStorefrontAPI</a></code></td>
<td>Field</td>
<td>Deprecated on the <code>MetafieldDefinition</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/MetafieldStorefrontAccess">MetafieldStorefrontAccess</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/MetafieldDefinitionCreateUserErrorCode#value-invalidinputcombination">INVALID_INPUT_COMBINATION</a></code></td>
<td>Value</td>
<td>Added to the <code>MetafieldDefinitionCreateUserError</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/metafieldDefinitionUpdate#field-metafielddefinitionupdatepayload-usererrors">INVALID_INPUT_COMBINATION</a></code></td>
<td>Error code</td>
<td>Added to the <code>MetafieldDefinitionUpdate</code> mutation</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Subscription billing attempts <span id="subscription-billing-attempts" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionBillingAttemptCreate"><code class="text-highlight text-highlight--grey">SubscriptionBillingAttemptCreate</code></a> mutation now prevents the creation of billing attempts if a subscription contract has one of the following terminal statuses:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">EXPIRED</code></li>
<li><code class="text-highlight text-highlight--grey">CANCELLED</code></li>
<li><code class="text-highlight text-highlight--grey">STALE</code></li>
</ul>
<p>We've also added the <a href="/docs/api/admin-graphql/2024-01/enums/BillingAttemptUserErrorCode#value-contractterminated"><code class="text-highlight text-highlight--grey">CONTRACT_TERMINATED</code></a> error code to the <code class="text-highlight text-highlight--grey">BillingAttemptUserErrorCode</code> enum. This new error code is returned in the case where billing attempt creation is prevented.</p>
<p><a href="/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt">Learn how to schedule and automate the billing of subscriptions</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Subscription billing cycles</h3>
</div>
<div class="accordion-content">
<p>You can now skip or unskip a <a href="/docs/apps/build/purchase-options/subscriptions/billing-cycles">subscription billing cycle</a> in a single operation. Your app can also receive webhook notifications to stay in sync with Shopify data or perform an action after a subscription billing cycle is skipped or unskipped.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for subscription contracts</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionBillingCycleSkip">subscriptionBillingCycleSkip</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionBillingCycleSkip">subscriptionBillingCycleUnskip</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptionbillingcyclesskip">SUBSCRIPTION_BILLING_CYCLES/SKIP/a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptionbillingcyclesunskip">SUBSCRIPTION_BILLING_CYCLES/UNSKIP</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Subscription contracts: Statuses <span id="subscription-contracts-statuses" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>The <code class="text-highlight text-highlight--grey">STALE</code> value on the <a href="/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus"><code class="text-highlight text-highlight--grey">SubscriptionContractSubscriptionStatus</code></a> enum has been removed. Existing subscription contracts with the <code class="text-highlight text-highlight--grey">STALE</code> status will be returned as <code class="text-highlight text-highlight--grey">CANCELLED</code>, and you won't be able to update the status of a subscription contract to <code class="text-highlight text-highlight--grey">STALE</code>.</p>
<p>Use the <a href="/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus#value-expired"><code class="text-highlight text-highlight--grey">EXPIRED</code></a> or <a href="/docs/api/admin-graphql/2024-01/enums/SubscriptionContractSubscriptionStatus#value-cancelled"><code class="text-highlight text-highlight--grey">CANCELLED</code></a> values instead.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Subscription contracts: New mutations and webhooks</h3>
</div>
<div class="accordion-content">
<p>You can now update the <code class="text-highlight text-highlight--grey">status</code> field of a <a href="/docs/apps/build/purchase-options/subscriptions/contracts">subscription contract</a> using newly available mutations. We've also introduced new webhook topics that notify your app when a subscription contract’s status is changed.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for subscription contracts</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionContractActivate">subscriptionContractActivate</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionContractPause">subscriptionContractPause</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionContractCancel">subscriptionContractCancel</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionContractFail">subscriptionContractFail</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/subscriptionContractExpire">subscriptionContractExpire</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/SubscriptionContractStatusUpdateUserError">SubscriptionContractStatusUpdateUserError</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptioncontractsactivate">SUBSCRIPTION_CONTRACTS/ACTIVATE</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptioncontractsexpire">SUBSCRIPTION_CONTRACTS/EXPIRE</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptioncontractsfail">SUBSCRIPTION_CONTRACTS/FAIL</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptioncontractscancel">SUBSCRIPTION_CONTRACTS/CANCEL</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-subscriptioncontractspause">SUBSCRIPTION_CONTRACTS/PAUSE</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Subscriptions support for automatic discounts</h3>
</div>
<div class="accordion-content">
<p>A subscription option for automatic discounts is now available to create automatic discounts for products.</p>
<p>In prior API versions, the <code class="text-highlight text-highlight--grey">DiscountType</code> classifies any automatic discount as <code class="text-highlight text-highlight--grey">MANUAL</code>. In API version 2024-01 and higher, the <a href="/docs/api/admin-graphql/2024-01/enums/DiscountType"><code class="text-highlight text-highlight--grey">DiscountType</code></a> enum accurately represents an automatic discount as <code class="text-highlight text-highlight--grey">AUTOMATIC_DISCOUNT</code>.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for subscriptions support of automatic discounts</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/DiscountType#value-automaticdiscount">AUTOMATIC_DISCOUNT</a></code></td>
<td>Value</td>
<td>Added to the <code>DiscountType</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/SubscriptionManualDiscount#field-subscriptionmanualdiscount-type">AUTOMATIC_DISCOUNT</a></code></td>
<td>Value</td>
<td>Added to the <code>type</code> field on the <code>SubscriptionManualDiscount</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Validation logic in cart and checkout</h3>
</div>
<div class="accordion-content">
<p>We've made improvements to the <a href="/docs/apps/build/checkout/cart-checkout-validation">validation logic</a> you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for validation logic in cart and checkout</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/validationCreate#argument-validation">validation</a></code></td>
<td>Argument</td>
<td>Added to the <code>validationCreate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/validationDelete#argument-validation">validation</a></code></td>
<td>Argument</td>
<td>Added to the <code>validationDelete</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/validationUpdate#argument-validation">validation</a></code></td>
<td>Argument</td>
<td>Added to the <code>validationUpdate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/MetafieldOwnerType#value-validation">VALIDATION</a></code></td>
<td>Value</td>
<td>Added to the <code>MetafieldOwnerType</code> enum</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Vaulting card data</h3>
</div>
<div class="accordion-content">
<p>Some credit card <a href="/docs/apps/build/payments">payment apps</a> now support vaulting card data in Shopify. This enables merchants to sell subscriptions, support card on file transactions, and use a variety of selling strategies in new ways.</p>
<p>To support payment apps with <a href="/docs/apps/build/purchase-options/subscriptions#subscription-apis">Subscription APIs</a>, we've added a <code class="text-highlight text-highlight--grey">processing</code> status to the <a href="/docs/api/admin-graphql/2024-01/mutations/customerPaymentMethodCreditCardCreate#field-customerpaymentmethodcreditcardcreatepayload-processing"><code class="text-highlight text-highlight--grey">customerPaymentMethodCreditCardCreate</code></a> and <a href="/docs/api/admin-graphql/2024-01/mutations/customerPaymentMethodCreditCardUpdate#field-customerpaymentmethodcreditcardupdatepayload-processing"><code class="text-highlight text-highlight--grey">customerPaymentMethodCreditCardUpdate</code></a> mutations. If <code class="text-highlight text-highlight--grey">processing</code> is <code class="text-highlight text-highlight--grey">true</code>, then you won't receive back payment method data, and should resend the same operation, with the same parameters, until you receive back user errors or the payment method data.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for vaulting card data</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/customerPaymentMethodCreditCardCreate#field-customerpaymentmethodcreditcardcreatepayload-processing">processing</a></code></td>
<td>Return field</td>
<td>Added to the <code>customerPaymentMethodCreditCardCreate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/customerPaymentMethodCreditCardUpdate#field-customerpaymentmethodcreditcardupdatepayload-processing">processing</a></code></td>
<td>Return field</td>
<td>Added to the <code>customerPaymentMethodCreditCardUpdate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/OrderPaymentStatusResult#value-initiated">INITIATED</a></code></td>
<td>Value</td>
<td>Added to the <code>OrderPaymentStatusResult</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/OrderPaymentStatusResult#value-pending">PENDING</a></code></td>
<td>Value</td>
<td>Added to the <code>OrderPaymentStatusResult</code> enum</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Visual representations of metaobjects</h3>
</div>
<div class="accordion-content">
<p>You can now use the <a href="/docs/api/admin-graphql/2024-01/objects/Metaobject#field-metaobject-thumbnailfield"><code class="text-highlight text-highlight--grey">thumbnailField</code></a> field to retrieve a visual representation of a metaobject. A metaobject's <code class="text-highlight text-highlight--grey">thumbnailField</code> field returns the preferred field to represent a metaobject visually. Valid field types are <code class="text-highlight text-highlight--grey">file</code>, for file references, and <code class="text-highlight text-highlight--grey">hex</code>, for colors.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for visual representations of metaobjects</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetaobjectThumbnail">MetaobjectThumbnail</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/Metaobject#field-metaobject-thumbnailfield">thumbnailField</a></code></td>
<td>Field</td>
<td>Added to the <code>Metaobject</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetaobjectDefinition#field-metaobjectdefinition-hasthumbnailfield">hasThumbnailField</a></code></td>
<td>Field</td>
<td>Added to the <code>MetaobjectDefinition</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/MetaobjectField#field-metaobjectfield-thumbnail">thumbnail</a></code></td>
<td>Field</td>
<td>Added to the <code>MetaobjectField</code> object</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Webhook sub-topics</h3>
</div>
<div class="accordion-content">
<p><a href="/docs/apps/build/webhooks/customize/sub-topics">Webhook sub-topics</a> are an extra level of grouping available for some webhook topics. Sub-topics work with topics to enable delivery of a more specific and relevant stream of webhooks to your app.</p>
<p>The following webhook topics now support sub-topics:</p>
<table>
<caption>New webhook topics that support sub-topics</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-metaobjectscreate">METAOBJECTS_CREATE</a></code></td>
<td>Webhook topic</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-metaobjectsupdate">METAOBJECTS_UPDATE</a></code></td>
<td>Webhook topic</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-metaobjectsdelete">METAOBJECTS_DELETE</a></code></td>
<td>Webhook topic</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
</table>
<p><strong>New types</strong></p>
<p>The following new types for webhook sub-topics are available:</p>
<table>
<caption>New types for webhook sub-topics</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/objects/WebhookSubscription#field-webhooksubscription-subtopic">subTopic</a></code></td>
<td>Field</td>
<td>Added to the <code>WebhookSubscription</code> object</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/eventBridgeWebhookSubscriptionCreate#argument-subtopic">subTopic</a></code></td>
<td>Argument</td>
<td>Added to the <code>EventBridgeWebhookSubscriptionCreate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/pubSubWebhookSubscriptionCreate#argument-subtopic">subTopic</a></code></td>
<td>Argument</td>
<td>Added to the <code>PubSubWebhookSubscriptionCreate</code> mutation</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/mutations/webhookSubscriptionCreate#argument-subtopic">subTopic</a></code></td>
<td>Argument</td>
<td>Added to the <code>WebhookSubscriptionCreate</code> mutation</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Webhook topics for discounts</h3>
</div>
<div class="accordion-content">
<p>We've introduced new webhook topics that are sent out when a discount has been created, updated, or deleted.</p>
<table>
<caption>New types for webhook topics for discounts</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-discountscreate">DISCOUNTS_CREATE</a></code></td>
<td>Value</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-discountsupdate">DISCOUNTS_UPDATE</a></code></td>
<td>Value</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-graphql/2024-01/enums/WebhookSubscriptionTopic#value-discountsdelete">DISCOUNTS_DELETE</a></code></td>
<td>Value</td>
<td>Added to the <code>WebhookSubscriptionTopic</code> enum</td>
</tr>
</table>
</div>
</div>
</div>
</div>
## REST Admin API changes
The following are all the changes currently introduced in the 2024-01 version of the REST Admin API.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Adjustment transactions</h3>
</div>
<div class="accordion-content">
<p>You can now view associated order details for an adjustment transaction using the Shopify Payments <a href="/docs/api/admin-rest/2024-01/resources/transactions">Transactions</a> resource. If a transaction is of type <code class="text-highlight text-highlight--grey">adjustment</code>, then order transaction details are available as an array in the <code class="text-highlight text-highlight--grey">adjustment_order_transactions</code> property.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Current quantity of line items</h3>
</div>
<div class="accordion-content">
<p>The <code class="text-highlight text-highlight--grey">current_quantity</code> property has been added to the <a href="/docs/api/admin-rest/2024-01/resources/order">Order</a> resource to indicate a line item's current quantity after removals.</p>
<p>If you're using refund line items to calculate a line item's current quantity, then we recommend migrating your app to use the new <code class="text-highlight text-highlight--grey">current_quantity</code> property, as it's a more reliable method.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Financial summaries</h3>
</div>
<div class="accordion-content">
<p>You can now retrieve the financial summary of a fulfillment order's line items.</p>
<p>The following new parameters have been added to the <code class="text-highlight text-highlight--grey">FulfillmentOrder</code> resource endpoints that <a href="/docs/api/admin-rest/2024-01/resources/fulfillmentorder#get-orders-order-id-fulfillment-orders">retrieve a list of fulfillment orders for a specific order</a>, and <a href="/docs/api/admin-rest/2024-01/resources/fulfillmentorder#get-fulfillment-orders-fulfillment-order-id">retrieve a specific fulfillment order</a>:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">include_financial_summaries</code>: The financial summary data for each fulfillment line item.</li>
<li><code class="text-highlight text-highlight--grey">include_order_reference_fields</code>: Whether order reference fields should be returned in the response.</li>
</ul>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Marketing properties <span id="marketing-properties" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>We've removed the following deprecated properties on the <a href="/docs/api/admin-rest/2024-01/resources/order"><code class="text-highlight text-highlight--grey">Order</code></a> and <a href="/docs/api/admin-rest/2024-01/resources/customer"><code class="text-highlight text-highlight--grey">Customer</code></a> resources:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">accepts_marketing</code></li>
<li><code class="text-highlight text-highlight--grey">accepts_marketing_updated_at</code></li>
<li><code class="text-highlight text-highlight--grey">marketing_opt_in_level</code></li>
</ul>
<p>Use the <a href="/docs/api/admin-rest/2024-01/resources/customer#resource-object"><code class="text-highlight text-highlight--grey">email_marketing_consent</code></a> property instead.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Sales tax remittance</h3>
</div>
<div class="accordion-content">
<p>The <code class="text-highlight text-highlight--grey">channel_liable</code> property on the <a href="/docs/api/admin-rest/2024-01/resources/order">Order</a> resource has been updated to reflect the value indicated by the app. The property lets you inform merchants that another party is responsible for sales tax remittance, which then helps merchants better understand the tax that they are responsible for.</p>
<p>The <code class="text-highlight text-highlight--grey">channel_liable</code> property can contain the following values:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">true</code>: Indicates that the channel is responsible for remittance of the tax line</li>
<li><code class="text-highlight text-highlight--grey">false</code>: Indicates that the channel isn't responsible for remittance of the tax line</li>
</ul>
<p>If the <code class="text-highlight text-highlight--grey">channel_liable</code> property isn't populated, then the value is <code class="text-highlight text-highlight--grey">false</code>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Separating and combining fulfillment order line items</h3>
</div>
<div class="accordion-content">
<p>We've added <a href="/docs/api/admin-rest/2024-01/resources/webhook">new webhook topics</a> that capture separating and combining line items inside a fulfillment order.</p>
<p><strong>New webhook topics</strong></p>
<p>The following new webhook topics are available:</p>
<table>
<caption>New fulfillment order webhook topics</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-rest/2024-01/resources/webhook#event-topics-fulfillment-orders-split">fulfillment_orders/split</a></code></td>
<td>Webhook topic</td>
<td>Added to the <code>Webhook</code> resource</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/admin-rest/2024-01/resources/webhook#event-topics-fulfillment-orders-split">fulfillment_orders/merged</a></code></td>
<td>Webhook topic</td>
<td>Added to the <code>Webhook</code> resource</td>
</tr>
</table>
</div>
</div>
</div>
</div>
## Storefront API changes
The following are all the changes currently introduced in the 2024-01 version of the Storefront API.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Validation logic in cart and checkout</h3>
</div>
<div class="accordion-content">
<p>We've made improvements to the <a href="/docs/apps/build/checkout/cart-checkout-validation">validation logic</a> you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.</p>
<p>The <a href="/docs/api/storefront/2024-01/enums/CartErrorCode#value-validationcustom"><code class="text-highlight text-highlight--grey">VALIDATION_CUSTOM</code></a> value has been added to <code class="text-highlight text-highlight--grey">CartUserError</code> enum.</p>
</div>
</div>
</div>
</div>
## Payments Apps API changes
The following are all the changes currently introduced in the 2024-01 version of the Payments Apps API.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Vaulting card data</h3>
</div>
<div class="accordion-content">
<p>Some credit card <a href="/docs/apps/build/payments">payment apps</a> now support vaulting card data in Shopify. This enables merchants to sell subscriptions, support card on file transactions, and use a variety of selling strategies in new ways.</p>
<p><strong>New types</strong></p>
<p>The following new types are available:</p>
<table>
<caption>New types for vaulting card data</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/mutations/verificationSessionReject">verificationSessionReject</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/mutations/verificationSessionResolve">verificationSessionResolve</a></code></td>
<td>Mutation</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/objects/VerificationSessionStateRejected">VerificationSessionStateRejected</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/objects/VerificationSessionStateResolved">VerificationSessionStateResolved</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/objects/VerificationSessionUserError">VerificationSessionUserError</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/objects/VerificationSession">VerificationSession</a></code></td>
<td>Object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/input-objects/VerificationSessionRejectionReasonInput">VerificationSessionRejectionReasonInput</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/input-objects/PaymentSessionThreeDSecureAuthenticationData">PaymentSessionThreeDSecureAuthenticationData</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/interfaces/VerificationSessionState">VerificationSessionState</a></code></td>
<td>Interface</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/unions/VerificationSessionStates">VerificationSessionStates</a></code></td>
<td>Union</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/enums/VerificationSessionStateCode">VerificationSessionStateCode</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/enums/VerificationSessionStateReason">VerificationSessionStateReason</a></code></td>
<td>Enum</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/payments-apps/2024-01/mutations/paymentSessionResolve#argument-networktransactionid">networkTransactionId</a></code></td>
<td>Argument</td>
<td>Added to the <code>paymentSessionResolve</code> mutation</td>
</tr>
</table>
</div>
</div>
</div>
</div>
## Shopify Function APIs changes
The following are all the changes currently introduced in the 2024-01 version of Shopify Function APIs.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Cart and Checkout Validation Function API</h3>
</div>
<div class="accordion-content">
<p>We've made improvements to the <a href="/docs/apps/build/checkout/cart-checkout-validation">validation logic</a> you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.</p>
<p>The <a href="/docs/api/functions/reference/cart-checkout-validation/graphql/input?api%5Bversion%5D=latest"><code class="text-highlight text-highlight--grey">validation</code></a> field has been added to <code class="text-highlight text-highlight--grey">Input</code> object.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Cart Transform Function API</h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/functions/reference/cart-transform/graphql/common-objects/expandoperation?api%5Bversion%5D=latest">Cart Transform Function API's <code class="text-highlight text-highlight--grey">ExpandOperation</code></a> object now enables you to set fixed prices on each component of a <a href="/docs/apps/build/product-merchandising/bundles">bundle</a>, resulting in a bundle price that's the sum of each component. The <code class="text-highlight text-highlight--grey">ExpandOperation</code> object also enables you to define a custom title and image for each parent line item. This update provides for more control over bundle pricing and enables bundles to be used for add-on products.</p>
<p>We've also added a new <a href="/docs/api/functions/reference/cart-transform/graphql/common-objects/updateoperation?api%5Bversion%5D=latest"><code class="text-highlight text-highlight--grey">UpdateOperation</code></a> object that allows you to override the price, title, and image of a given line item. This gives you more more flexibility to make additional customizations to items in the cart.</p>
<p><a href="/docs/api/functions/reference/cart-transform">Learn more about the Cart Transform Function API</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Handle as a scalar type <span id="handle-as-a-scalar-type" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>The following fields and arguments that return a handle to identify a Function resource now use the appropriate <code class="text-highlight text-highlight--grey">Handle</code> scalar as their type:</p>
<table>
<caption>Fields and arguments that use <code>Handle</code> as a scalar type</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>CartDeliveryOption</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>Product</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>MoveOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/moveoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>RenameOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/renameoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>deliveryOptionHandle</code></td>
<td>Field</td>
<td>On the <code>HideOperation</code> input object (<a href="/docs/api/functions/reference/delivery-customization/graphql/common-objects/hideoperation?api%5Bversion%5D=latest">Delivery Customization API</a>)</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>GateConfiguration</code> object for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Argument</td>
<td>On the <code>HasGates</code> interface for all Function APIs</td>
</tr>
<tr>
<td scope="row"><code>handle</code></td>
<td>Field</td>
<td>On the <code>Market</code> object for all Function APIs</td>
</tr>
</table>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>New fields on all Shopify Function APIs</h3>
</div>
<div class="accordion-content">
<p>The following new fields have been added to all <a href="/docs/api/functions">Shopify Function APIs</a> on the <code class="text-highlight text-highlight--grey">Customer</code> object:</p>
<ul>
<li><code class="text-highlight text-highlight--grey">firstName</code>: The customer's first name.</li>
<li><code class="text-highlight text-highlight--grey">lastName</code>: The customer's last name.</li>
</ul>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Order Routing Location Rule API</h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/functions/reference/order-routing-location-rule/graphql/common-objects/fulfillmentgroup?api%5Bversion%5D=latest"><code class="text-highlight text-highlight--grey">deliveryAddress</code></a> field was added to the <code class="text-highlight text-highlight--grey">FulfillmentGroup</code> object.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Product Discount Function API</h3>
</div>
<div class="accordion-content">
<p>The Product Discount Function API now supports setting the <a href="/docs/api/functions/reference/product-discounts/graphql/common-objects/discountapplicationstrategy"><code class="text-highlight text-highlight--grey">discountApplicationStrategy</code> enum to the value of <code class="text-highlight text-highlight--grey">ALL</code></a> in the <code class="text-highlight text-highlight--grey">FunctionRunResult</code>. You can use this option to apply all applicable discounts returned by a product discount function.</p>
<p><a href="/docs/apps/build/discounts">Learn how to build a discounts experience with Shopify Functions</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Shipping Discount Function API: Field removal <span id="discount-application-strategy" class="heading-flag breaking"></h3>
</div>
<div class="accordion-content">
<p>We've removed the deprecated <code class="text-highlight text-highlight--grey">discountApplicationStrategy</code> field on the <a href="/docs/api/functions/reference/shipping-discounts/graphql/functionrunresult?api%5Bversion%5D=latest"><code class="text-highlight text-highlight--grey">FunctionRunResult</code></a> object, and its predecessor, the <a href="/docs/api/functions/reference/shipping-discounts/graphql/functionresult?api%5Bversion%5D=latest"><code class="text-highlight text-highlight--grey">FunctionResult</code></a> object.</p>
<p>The discount application strategy for shipping discount functions is always considered to be <code class="text-highlight text-highlight--grey">ALL</code>. This means that all applicable discounts are returned by a shipping discount function.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Shipping Discount Function API: Public availability</h3>
</div>
<div class="accordion-content">
<p>The <a href="/docs/api/functions/reference/shipping-discounts">Shipping Discount Function API</a> is now publicly available to use on all merchant stores. The API can be used for the following use cases:</p>
<ul>
<li>Discounting specific delivery options. For example, free standard shipping only.</li>
<li>Discounting shipping based on the contents of a cart. For example, buy this candle and get free shipping.</li>
<li>Discounting shipping based on buyer identity. For example, discounting based on how many orders a customer has placed.</li>
</ul>
<p><strong>New types</strong></p>
<p>The following new delivery option types are also available:</p>
<table>
<caption>New delivery options types in the Shipping Discount Function API</caption>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Change</th>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/functions/reference/shipping-discounts/graphql/common-objects/deliveryoptiontarget?api%5Bversion%5D=latest">DeliveryOptionTarget</a></code></td>
<td>Input object</td>
<td>Added</td>
</tr>
<tr>
<td scope="row"><code><a href="/docs/api/functions/reference/shipping-discounts/graphql/common-objects/target?api%5Bversion%5D=latest">deliveryOption</a></code></td>
<td>Field</td>
<td>Added to the <code>Target</code> object</td>
</tr>
</table>
</div>
</div>
</div>
</div>
## Introducing the Customer Account API
The [Customer Account API](/docs/api/customer) is a new API that's available as of the 2024-01 release. The API offers a secure and private way of accessing private customer-scoped data, such as customer, orders, payments, fulfillment, discounts, refunds, and metafields.
<div class="accordion-container">
<div class="accordion-controls">
<button class="accordion-control" data-accordion-control-type="expand-all" type="button">Expand all</button>
</div>
<div class="accordion-content-container">
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Building personalized customer experiences</h3>
</div>
<div class="accordion-content">
<p>The Customer Account API enables you to build personalized customer experiences that you can use in your <a href="/docs/storefronts/headless/building-with-the-customer-account-api/hydrogen">Headless or Hydrogen custom storefronts</a>. The API offers a full range of options making it possible for customers to view their orders, manage their profile, and much more.</p>
<p>Version 2024-01 is the base version of the Customer Account API. We strongly recommend that you update your apps to call the 2024-01 API version. To learn how to update your app to begin calling an API version, refer to <a href="/docs/api/usage/versioning">Shopify API versioning</a>.</p>
<p>You can <a rel="external noreferrer noopener" target="_blank" href="https://github.com/Shopify/hydrogen/discussions">provide feedback</a> to help shape future iterations of the Customer Account API.</p>
<p>Learn more about <a href="/docs/storefronts/headless/building-with-the-customer-account-api">building with the Customer Account API</a>.</p>
</div>
</div>
<div class="accordion-item">
<div class="accordion-link">
<div class="chevron-up"></div>
<div class="chevron-down"></div>
<h3>Delivery options</h3>
</div>
<div class="accordion-content">
<p>You can now query the available delivery options for a subscription contract using the <a href="/docs/api/customer/2024-01/mutations/subscriptionContractFetchDeliveryOptions"><code class="text-highlight text-highlight--grey">subscriptionContractFetchDeliveryOptions</code></a> mutation.</p>
<p>You can also select an option from a delivery options result and update the delivery method on a subscription contract using the <a href="/docs/api/customer/2024-01/mutations/subscriptionContractSelectDeliveryMethod"><code class="text-highlight text-highlight--grey">subscriptionContractSelectDeliveryMethod</code></a> mutation.</p>
</div>
</div>
</div>
</div>