2024-01 release notes

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.

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.

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.

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

The following new types are available:

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

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

The following new types are available:

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

The following new types are available:

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

The following new types are available:

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

Learn more about Shopify Markets.

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.

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

The following new types are available:

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.

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.

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.

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.

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

New types

The following new types are available:

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

• acceptsMarketing
• acceptsMarketingUpdatedAt
• MarketingOptInLevel

Use the emailMarketingConsent field instead.

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

New types

The following new types are available:

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.

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

The following new types are available:

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

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

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

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

Use the mediaId and mediaSrc fields instead.

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

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:

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:

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:

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:

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.

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:

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.

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:

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:

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:

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:

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:

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:

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

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.

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.

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.

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.

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.

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:

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.

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:

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.

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.

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

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.

The deliveryAddress field was added to the FulfillmentGroup object.

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.

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.

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:

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.

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.