2024-01 release notes

What's new in 2024-01

The 2024-01 version of Shopify's APIs include the following highlights:

• Buy X Get Y discounts now support setting a fixed amount discount.
• The new orderCancel mutation enables you to cancel orders.
• You can now schedule changes to inventory quantities.
• More granular capabilities are available for separating and combining line items inside a fulfillment order.
• You can now update and remove discounts when editing orders.
• Various improvements have been made to subscription contracts, subscription billing attempts, metaobjects, metafield definitions, and marketing activities.
• Webhook sub-topics enable the delivery of a more specific and relevant stream of webhooks to your app.
• New types enable some credit card payment apps to support vaulting card data in Shopify.
• Several improvements have been made to Shopify Function APIs.
• The new Customer Account API offers a secure and private way of accessing private customer-scoped data.

Anchor to Breaking changesBreaking changes

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

Anchor to Change to AppSubscriptionDiscountInputChange to AppSubscriptionDiscountInput

The 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.

Anchor to Field deprecation on ProductInputField deprecation on ProductInput

We've deprecated the images field on the ProductInput input object.

Use the media argument on the productCreate and productUpdate mutations instead.

Anchor to Field removals on ProductVariantInputField removals on ProductVariantInput

We've removed the deprecated imageId and imageSrc fields from the ProductVariantInput input object.

Use the mediaId and mediaSrc fields instead.

Anchor to Field removal on the Shipping Discount Function APIField removal on the Shipping Discount Function API

We've removed the deprecated discountApplicationStrategy field on the FunctionRunResult object, and its predecessor, the FunctionResult 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.

Anchor to Handle as a scalar type on Shopify Function APIsHandle as a scalar type on Shopify Function APIs

The following fields and arguments that return a handle to identify a Function resource now use the appropriate Handle scalar as their type:

Anchor to Marketing activitiesMarketing activities

The following breaking changes have been made to marketing activity types on the GraphQL Admin API:

• The channel field on the marketingActivityCreateExternal and marketingActivityUpdateExternal mutations has been renamed to marketingChannelType.

• utcOffset and isCumulative are now required fields on the marketingEngagementInput input object.

• The fetchedAt field has been removed from the marketingEngagementInput input object.

• The utm field has been deprecated from the MarketingActivityUpdateExternalInput input object.

Anchor to Marketing fields and properties removalsMarketing fields and properties removals

• GraphQL Admin API: We've removed the following deprecated fields on the Customer object and CustomerInput input object:

  • acceptsMarketing

  • acceptsMarketingUpdatedAt

  • MarketingOptInLevel

    Use the emailMarketingConsent field instead.

• REST Admin API: We've removed the following deprecated properties on the Order and Customer resources:

  • accepts_marketing

  • accepts_marketing_updated_at

  • marketing_opt_in_level

    Use the email_marketing_consent property instead.

Anchor to Subscription billing attemptsSubscription billing attempts

The 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 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.

Anchor to Subscription contractsSubscription contracts

The STALE value on the 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 or CANCELLED values instead.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

The following are all the changes currently introduced in the 2024-01 version of the GraphQL Admin API.

Anchor to Abandoned checkoutsAbandoned checkouts

You can now query a single line item in an abandoned checkout by using the AbandonedCheckoutLineItem object. The title field on the AbandonedCheckoutLineItem object, which defaults to the product title, can now also accept a null value.

Anchor to App subscription discountsApp subscription discounts

Anchor to BreakingBreaking

The 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.

Anchor to Buy X Get Y discountsBuy X Get Y discounts

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.

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 GraphQL Admin API.

Learn how to create and manage different types of discounts.

Anchor to Cancelling ordersCancelling orders

You can now use the orderCancel 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.

The mutation performs cancellation asynchronously in a background job and returns a Job object that you can query to poll for the cancellation status.

New types

Anchor to Capturing transactions multiple timesCapturing transactions multiple times

You can now use the multiCapturable field on the OrderTransaction object to determine whether a transaction can be captured multiple times.

Anchor to Cart and checkout operationsCart and checkout operations

The CartTransformCreate mutation now supports a blockOnFailure argument that determines if cart and checkout operations should be blocked if a Cart Transform function 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.

New types

Anchor to Checkout brandingCheckout branding

You can now use the checkoutBrandingUpsert mutation to reset branding settings to their default state without resetting each field explicitly. You can pass a null value to the checkoutBrandingInput argument to clear all of the branding settings, which will revert the branding of the checkout to its default state.

You can also use the GraphQL Admin API to customize the look of the ChoiceList components in checkout.

New types

Anchor to Customer data erasureCustomer data erasure

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.

To learn more about how data erasure is processed and the impact on customer data, refer to Processing customer data requests.

New types

Anchor to Deleting market regionsDeleting market regions

You can now use the marketRegionsDelete mutation to delete a list of market regions.

Learn more about Shopify Markets.

Anchor to Filtering pricesFiltering prices

You can now use a new query parameter on the prices connection of the PriceList object to filter prices for each product or product variant ID.

For example, prices(first: 10, query: "product_id:1") filters the first ten prices of a product with an ID of gid://shopify/Product/1.

Similarly, prices(first: 10, query: "variant_id:1") filters the first ten prices for a product variant with an ID of gid://shopify/ProductVariant/1.

Anchor to Financial summariesFinancial summaries

You can now use the financialSummaries field on the FulfillmentOrderLineItem object to retrieve the financial summary of a fulfillment order's line items.

With this change, order information that's required to calculate the financial specifics of an order is accessible using the fulfillmentOrder.lineItems connection and any of the fulfillment_orders access scopes. The same data is available using fulfillmentOrder.order.lineItems, but requires the read_orders access scope.

New types

Anchor to Fulfillment hold reasonsFulfillment hold reasons

A new fulfillment hold reason (AWAITING_RETURN_ITEMS) is now applied to a fulfillment hold on a fulfillment order when a return is created with exchange items.

Anchor to Including translations when duplicating productsIncluding translations when duplicating products

You can now specify whether to include translations when you run the productDuplicate mutation. If you specify the optional includeTranslations argument as true, then all translations that are saved on the product and its associated variants and metafields are copied over to the new product.

Anchor to Localizing metaobjects for different marketsLocalizing metaobjects for different markets

Metaobjects are now exposed as a value on the MarketLocalizableResourceType 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 Translate and Adapt app. Localizable fields are determined by the metaobject type.

Anchor to Marketing activities: Field changesMarketing activities: Field changes

Anchor to BreakingBreaking

The following breaking changes have been made to marketing activity types:

• The channel field on the marketingActivityCreateExternal and marketingActivityUpdateExternal mutations has been renamed to marketingChannelType.

• utcOffset and isCumulative are now required fields on the marketingEngagementInput input object.

• The fetchedAt field has been removed from the marketingEngagementInput input object.

• The utm field has been deprecated from the MarketingActivityUpdateExternalInput input object.

Anchor to Marketing activites: ImprovementsMarketing activites: Improvements

We've made improvements to creating marketing activities, syncing aggregate marketing activity data, and deleting marketing activities.

New types

Anchor to Marketing fieldsMarketing fields

Anchor to BreakingBreaking

We've removed the following deprecated fields on the Customer object and CustomerInput input object:

• acceptsMarketing

• acceptsMarketingUpdatedAt

• MarketingOptInLevel

  Use the emailMarketingConsent field instead.

Anchor to Metaobjects and metaobject definitionsMetaobjects and metaobject definitions

We've added new fields so that you can query for the user or app that created a metaobject or metaobject definition.

New types

Anchor to New metafields error codeNew metafields error code

We've added the CAPABILITY_VIOLATION error code to the MetafieldsSetUserErrorCode enum. The error code is returned if you attempt to update a metafield in a way that doesn't conform to the enabled capabilities.

Anchor to Order editingOrder editing

You can now update and remove discounts when editing orders. To learn more about using discounts with order edits, refer to Edit an existing order.

New types

Anchor to Order routingOrder routing

The ORDER_ROUTING_LOCATION_RULE value has been added to the MetafieldOwnerType enum. To learn more about order routing, refer to Order routing apps.

Anchor to Product imagesProduct images

Anchor to BreakingBreaking

We've deprecated the images field on the ProductInput input object.

Use the media argument on the productCreate and productUpdate mutations instead.

Anchor to Product variant imagesProduct variant images

Anchor to BreakingBreaking

We've removed the deprecated imageId and imageSrc fields from the ProductVariantInput input object.

Use the mediaId and mediaSrc fields instead.

Anchor to Retrieving payment details for transactionsRetrieving payment details for transactions

You can now use the paymentDetails field on the SuggestedOrderTransaction object to retrieve payment details that are related to a transaction.

Anchor to Scheduling changes to inventory quantitiesScheduling changes to inventory quantities

You can now schedule changes to inventory quantities using the InventorySetScheduledChanges mutation. 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 incoming to available. Information about scheduled changes to inventory quantities can help merchants make better buying or selling decisions.

New types

The following new types are available:

Anchor to Separating and combining fulfillment order line itemsSeparating and combining fulfillment order line items

We've added more granular capabilities for separating and combining line items inside a fulfillment order so that you can partially fulfill an order or change the location of specific line items.

New types

The following new types are available:

New webhook topics

The following new webhook topics are available:

Anchor to Shopify Payments balance transactionsShopify Payments balance transactions

You can now use the GraphQL Admin API to query transactions that are associated with a Shopify Payments account balance.

New types

The following new types are available:

Anchor to Storefront access controls for custom dataStorefront access controls for custom data

We've modified storefront access controls to be more explicit for custom data. The changes affect how you can modify app reserved prefixes in the Shopify admin and how apps set access controls.

App reserved prefixes are configurable. For example, if you set access for admin to be MERCHANT_READ and storefront to be PUBLIC_READ 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.

Learn more about access controls for metafields and metaobjects.

New types

The following new types are available:

Anchor to Subscription billing attemptsSubscription billing attempts

Anchor to BreakingBreaking

The 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 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.

Anchor to Subscription billing cyclesSubscription billing cycles

You can now skip or unskip a subscription billing cycle 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.

New types

The following new types are available:

Anchor to Subscription contracts: StatusesSubscription contracts: Statuses

Anchor to BreakingBreaking

The STALE value on the 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 or CANCELLED values instead.

Anchor to Subscription contracts: New mutations and webhooksSubscription contracts: New mutations and webhooks

You can now update the status field of a subscription contract using newly available mutations. We've also introduced new webhook topics that notify your app when a subscription contract's status is changed.

New types

The following new types are available:

Anchor to Subscriptions support for automatic discountsSubscriptions support for automatic discounts

A subscription option for automatic discounts is now available to create automatic discounts for products.

In prior API versions, the DiscountType classifies any automatic discount as MANUAL. In API version 2024-01 and higher, the DiscountType enum accurately represents an automatic discount as AUTOMATIC_DISCOUNT.

New types

The following new types are available:

Anchor to Validation logic in cart and checkoutValidation logic in cart and checkout

We've made improvements to the validation logic you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.

New types

The following new types are available:

Anchor to Vaulting card dataVaulting card data

Some credit card payment apps 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.

To support payment apps with Subscription APIs, we've added a processing status to the customerPaymentMethodCreditCardCreate and customerPaymentMethodCreditCardUpdate mutations. If processing is true, 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.

New types

The following new types are available:

Anchor to Visual representations of metaobjectsVisual representations of metaobjects

You can now use the thumbnailField field to retrieve a visual representation of a metaobject. A metaobject's thumbnailField field returns the preferred field to represent a metaobject visually. Valid field types are file, for file references, and hex, for colors.

New types

The following new types are available:

Anchor to Webhook sub-topicsWebhook sub-topics

Webhook sub-topics 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.

The following webhook topics now support sub-topics:

New types

The following new types for webhook sub-topics are available:

Anchor to Webhook topics for discountsWebhook topics for discounts

We've introduced new webhook topics that are sent out when a discount has been created, updated, or deleted.

Anchor to REST Admin API changesREST Admin API changes

The following are all the changes currently introduced in the 2024-01 version of the REST Admin API.

Anchor to Adjustment transactionsAdjustment transactions

You can now view associated order details for an adjustment transaction using the Shopify Payments Transactions resource. If a transaction is of type adjustment, then order transaction details are available as an array in the adjustment_order_transactions property.

Anchor to Current quantity of line itemsCurrent quantity of line items

The current_quantity property has been added to the Order resource to indicate a line item's current quantity after removals.

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 current_quantity property, as it's a more reliable method.

Anchor to Financial summariesFinancial summaries

You can now retrieve the financial summary of a fulfillment order's line items.

The following new parameters have been added to the FulfillmentOrder resource endpoints that retrieve a list of fulfillment orders for a specific order, and retrieve a specific fulfillment order:

• include_financial_summaries: The financial summary data for each fulfillment line item.
• include_order_reference_fields: Whether order reference fields should be returned in the response.

Anchor to Marketing propertiesMarketing properties

Anchor to BreakingBreaking

We've removed the following deprecated properties on the Order and Customer resources:

• accepts_marketing

• accepts_marketing_updated_at

• marketing_opt_in_level

  Use the email_marketing_consent property instead.

Anchor to Sales tax remittanceSales tax remittance

The channel_liable property on the Order 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.

The channel_liable property can contain the following values:

• true: Indicates that the channel is responsible for remittance of the tax line

• false: Indicates that the channel isn't responsible for remittance of the tax line

  If the channel_liable property isn't populated, then the value is false.

Anchor to Separating and combining fulfillment order line itemsSeparating and combining fulfillment order line items

We've added new webhook topics that capture separating and combining line items inside a fulfillment order.

New webhook topics

The following new webhook topics are available:

Anchor to Storefront API changesStorefront API changes

The following are all the changes currently introduced in the 2024-01 version of the Storefront API.

Anchor to Validation logic in cart and checkoutValidation logic in cart and checkout

We've made improvements to the validation logic you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.

The VALIDATION_CUSTOM value has been added to CartUserError enum.

Anchor to Payments Apps API changesPayments Apps API changes

The following are all the changes currently introduced in the 2024-01 version of the Payments Apps API.

Anchor to Vaulting card dataVaulting card data

Some credit card payment apps 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.

New types

The following new types are available:

Anchor to Shopify Function APIs changesShopify Function APIs changes

The following are all the changes currently introduced in the 2024-01 version of Shopify Function APIs.

Anchor to Cart and Checkout Validation Function APICart and Checkout Validation Function API

We've made improvements to the validation logic you can add to cart and checkout. These improvements enable merchants to ensure order compliance with their business rules.

The validation field has been added to Input object.

Anchor to Cart Transform Function APICart Transform Function API

The Cart Transform Function API's ExpandOperation object now enables you to set fixed prices on each component of a bundle, resulting in a bundle price that's the sum of each component. The ExpandOperation 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.

We've also added a new UpdateOperation 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.

Learn more about the Cart Transform Function API.

Anchor to Handle as a scalar typeHandle as a scalar type

Anchor to BreakingBreaking

The following fields and arguments that return a handle to identify a Function resource now use the appropriate Handle scalar as their type:

Anchor to New fields on all Shopify Function APIsNew fields on all Shopify Function APIs

The following new fields have been added to all Shopify Function APIs on the Customer object:

• firstName: The customer's first name.
• lastName: The customer's last name.

Anchor to Order Routing Location Rule APIOrder Routing Location Rule API

The deliveryAddress field was added to the FulfillmentGroup object.

Anchor to Product Discount Function APIProduct Discount Function API

The Product Discount Function API now supports setting the discountApplicationStrategy enum to the value of ALL in the FunctionRunResult. You can use this option to apply all applicable discounts returned by a product discount function.

Learn how to build a discounts experience with Shopify Functions.

Anchor to Shipping Discount Function API: Field removalShipping Discount Function API: Field removal

Anchor to BreakingBreaking

We've removed the deprecated discountApplicationStrategy field on the FunctionRunResult object, and its predecessor, the FunctionResult 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.

Anchor to Shipping Discount Function API: Public availabilityShipping Discount Function API: Public availability

The Shipping Discount Function API is now publicly available to use on all merchant stores. The API can be used for the following use cases:

• Discounting specific delivery options. For example, free standard shipping only.
• Discounting shipping based on the contents of a cart. For example, buy this candle and get free shipping.
• Discounting shipping based on buyer identity. For example, discounting based on how many orders a customer has placed.

New types

The following new delivery option types are also available:

Anchor to Introducing the Customer Account APIIntroducing the Customer Account API

The Customer Account API 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.

Anchor to Building personalized customer experiencesBuilding personalized customer experiences

The Customer Account API enables you to build personalized customer experiences that you can use in your Headless or Hydrogen custom storefronts. The API offers a full range of options making it possible for customers to view their orders, manage their profile, and much more.

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 Shopify API versioning.

You can provide feedback to help shape future iterations of the Customer Account API.

Learn more about building with the Customer Account API.

Anchor to Delivery optionsDelivery options

You can now query the available delivery options for a subscription contract using the subscriptionContractFetchDeliveryOptions mutation.

You can also select an option from a delivery options result and update the delivery method on a subscription contract using the subscriptionContractSelectDeliveryMethod mutation.