2024-01 release notes (Release candidate)
| Release date | Date version is no longer supported |
|---|---|
| January 1, 2024 | January 1, 2025 |
Breaking changes
Anchor link to section titled "Breaking changes"These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.
Field deprecation on ProductInput
Anchor link to section titled "Field 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.
Field removals on ProductVariantInput
Anchor link to section titled "Field removals on ProductVariantInput"We've removed the deprecated imageId and imageSrc fields from the ProductVariantInput input object.
Use the mediaId and mediaSrc fields instead.
Change to AppSubscriptionDiscountInput
Anchor link to section titled "Change 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.
GraphQL Admin API changes
Anchor link to section titled "GraphQL Admin API changes"The following are all the changes currently introduced in the 2024-01 version of the GraphQL Admin API.
App subscription discounts
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.
Capturing transactions multiple times
You can now use the multiCapturable field on the OrderTransaction object to determine whether a transaction can be captured multiple times.
Checkout 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
The following new types are available:
| Name | Type | Change |
|---|---|---|
checkoutBrandingUpsert |
Mutation | Added |
choiceList |
Field | Added to the CheckoutBrandingCustomizationsInput input object |
choiceList |
Field | Added to the CheckoutBrandingCustomizations object |
Customer 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
The following new types are available:
| Name | Type | Change |
|---|---|---|
customerRequestDataErasure |
Mutation | Added |
customerCancelDataErasure |
Mutation | Added |
CustomerRequestDataErasureUserError |
Object | Added |
CustomerCancelDataErasureUserError |
Object | Added |
Deleting market regions
You can now use the marketRegionsDelete mutation to delete a list of market regions.
Filtering 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.
Financial 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
The following new types are available:
| Name | Type | Change |
|---|---|---|
FulfillmentOrderLineItemFinancialSummary |
Object | Added |
FinancialSummaryDiscountAllocation |
Object | Added |
FinancialSummaryDiscountApplication |
Object | Added |
financialSummaries |
Field | Added to the FulfillmentOrderLineItem object |
Including 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.
Localizing 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.
Metaobjects 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
The following new types are available:
| Name | Type | Change |
|---|---|---|
createdByApp |
Field | Added to the MetaobjectDefinition object |
createdByStaff |
Field | Added to the MetaobjectDefinition object |
createdByApp |
Field | Added to the Metaobject object |
createdByStaff |
Field | Added to the Metaobject object |
New 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.
Order 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
The following new types are available:
| Name | Type | Change |
|---|---|---|
orderEditUpdateDiscount |
Mutation | Added |
orderEditRemoveDiscount |
Mutation | Added |
Product images
We've deprecated the images field on the ProductInput input object.
Use the media argument on the productCreate and productUpdate mutations instead.
Product variant images
We've removed the deprecated imageId and imageSrc fields from the ProductVariantInput input object.
Retrieving 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.
Scheduling 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:
| Name | Type | Change |
|---|---|---|
InventorySetScheduledChanges |
Mutation | Added |
InventoryScheduledChange |
Object | Added |
InventoryScheduledChangeInput |
Input object | Added |
InventoryScheduledChangeItemInput |
Input object | Added |
InventorySetScheduledChangesInput |
Input object | Added |
scheduledChanges |
Connection | Added to the InventoryLevel object |
Separating 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:
| Name | Type | Change |
|---|---|---|
lineItemIds |
Argument | Added to the locationsForMove connection on the FulfillmentOrder object |
query |
Argument | Added to the locationsForMove connection on the FulfillmentOrder object |
locationIds |
Argument | Added to the locationsForMove connection on the FulfillmentOrder object |
fulfillmentOrdersForMerge |
Connection | Added to the FulfillmentOrder object |
availableLineItems |
Connection | Added to the FulfillmentOrderLocationForMove object |
unavailableLineItems |
Connection | Added to the FulfillmentOrderLocationForMove object |
availableLineItemsCount |
Field | Added to the FulfillmentOrderLocationForMove object |
unavailableLineItemsCount |
Field | Added to the FulfillmentOrderLocationForMove object |
NO_LINE_ITEMS_PROVIDED_TO_SPLIT |
Field | Added to the FulfillmentOrderSplitUserErrorCode enum |
New webhook topics
The following new webhook topics are available:
| Name | Type | Change |
|---|---|---|
FULFILLMENT_ORDERS_SPLIT |
Value | Added to the WebhookSubscriptionTopic enum |
FULFILLMENT_ORDERS_MERGED |
Value | Added to the WebhookSubscriptionTopic enum |
Storefront 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:
| Name | Type | Change |
|---|---|---|
storefront |
Field | Added to the MetafieldAccessInput input object |
storefront |
Field | Added to the MetafieldAccessUpdateInput input object |
storefront |
Field | Added to the MetafieldAccess object |
visibleToStorefrontAPI |
Field | Added to the MetafieldDefinitionInput input object |
visibleToStorefrontAPI |
Field | Added to the MetafieldDefinitionUpdateInput input object |
visibleToStorefrontAPI |
Field | Deprecated on the MetafieldDefinition object |
MetafieldStorefrontAccess |
Enum | Added |
INVALID_INPUT_COMBINATION |
Value | Added to the MetafieldDefinitionCreateUserError enum |
INVALID_INPUT_COMBINATION |
Error code | Added to the MetafieldDefinitionUpdate mutation |
Subscription 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:
| Name | Type | Change |
|---|---|---|
subscriptionBillingCycleSkip |
Mutation | Added |
subscriptionBillingCycleUnskip |
Mutation | Added |
SUBSCRIPTION_BILLING_CYCLES/SKIP/a> |
Enum | Added |
SUBSCRIPTION_BILLING_CYCLES/UNSKIP |
Enum | Added |
Subscription contracts
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:
| Name | Type | Change |
|---|---|---|
subscriptionContractActivate |
Mutation | Added |
subscriptionContractPause |
Mutation | Added |
subscriptionContractCancel |
Mutation | Added |
subscriptionContractFail |
Mutation | Added |
subscriptionContractExpire |
Mutation | Added |
SubscriptionContractStatusUpdateUserError |
Enum | Added |
SUBSCRIPTION_CONTRACTS/ACTIVATE |
Enum | Added |
SUBSCRIPTION_CONTRACTS/EXPIRE |
Enum | Added |
SUBSCRIPTION_CONTRACTS/FAIL |
Enum | Added |
SUBSCRIPTION_CONTRACTS/CANCEL |
Enum | Added |
SUBSCRIPTION_CONTRACTS/PAUSE |
Enum | Added |
Subscriptions 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:
| Name | Type | Change |
|---|---|---|
AUTOMATIC_DISCOUNT |
Value | Added to the DiscountType enum |
AUTOMATIC_DISCOUNT |
Value | Added to the type field on the SubscriptionManualDiscount object |
Vaulting 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:
| Name | Type | Change |
|---|---|---|
processing |
Return field | Added to the customerPaymentMethodCreditCardCreate mutation |
processing |
Return field | Added to the customerPaymentMethodCreditCardUpdate mutation |
INITIATED |
Value | Added to the OrderPaymentStatusResult enum |
PENDING |
Value | Added to the OrderPaymentStatusResult enum |
Visual 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:
| Name | Type | Change |
|---|---|---|
MetaobjectThumbnail |
Object | Added |
thumbnailField |
Field | Added to the Metaobject object |
hasThumbnailField |
Field | Added to the MetaobjectDefinition object |
thumbnail |
Field | Added to the MetaobjectField object |
Webhook 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:
| Name | Type | Change |
|---|---|---|
METAOBJECTS_CREATE |
Webhook topic | Added to the WebhookSubscriptionTopic enum |
METAOBJECTS_UPDATE |
Webhook topic | Added to the WebhookSubscriptionTopic enum |
METAOBJECTS_DELETE |
Webhook topic | Added to the WebhookSubscriptionTopic enum |
New types
The following new types for webhook sub-topics are available:
| Name | Type | Change |
|---|---|---|
subTopic |
Field | Added to the WebhookSubscription object |
subTopic |
Argument | Added to the EventBridgeWebhookSubscriptionCreate mutation |
subTopic |
Argument | Added to the PubSubWebhookSubscriptionCreate mutation |
subTopic |
Argument | Added to the WebhookSubscriptionCreate mutation |
REST Admin API changes
Anchor link to section titled "REST Admin API changes"The following are all the changes currently introduced in the 2024-01 version of the REST Admin API.
Adjustment 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.
Financial 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.
Separating 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:
| Name | Type | Change |
|---|---|---|
fulfillment_orders/split |
Webhook topic | Added to the Webhook resource |
fulfillment_orders/merged |
Webhook topic | Added to the Webhook resource |
Payments Apps API changes
Anchor link to section titled "Payments Apps API changes"The following are all the changes currently introduced in the 2024-01 version of the Payments Apps API.
Vaulting 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:
| Name | Type | Change |
|---|---|---|
verificationSessionReject |
Mutation | Added |
verificationSessionResolve |
Mutation | Added |
VerificationSessionStateRejected |
Object | Added |
VerificationSessionStateResolved |
Object | Added |
VerificationSessionUserError |
Object | Added |
VerificationSession |
Object | Added |
VerificationSessionRejectionReasonInput |
Input object | Added |
PaymentSessionThreeDSecureAuthenticationData |
Input object | Added |
VerificationSessionState |
Interface | Added |
VerificationSessionStates |
Union | Added |
VerificationSessionStateCode |
Enum | Added |
VerificationSessionStateReason |
Enum | Added |
networkTransactionId |
Argument | Added to the paymentSessionResolve mutation |
Shopify Function APIs changes
Anchor link to section titled "Shopify Function APIs changes"The following are all the changes currently introduced in the 2024-01 version of Shopify Function APIs.
Product discounts
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.