Developer changelog

As of 2024-01 Metaobjects will be exposed as a MarketLocalizableResourceType. This means that metaobjects with the translatable capability will be eligible for custom content by market through the Translations API as well as the Translate and Adapt app. Localizable fields will be determined by the Metaobject type.

As of 2024-01 the OrderTransaction endpoint now exposes the multiCapturable field, to inform whether a transaction can be captured multiple times.

Learn more about OrderTransaction.

As of API version 2024-01, the following customer resource fields have been removed: acceptsMarketing, acceptsMarketingUpdatedAt, and MarketingOptInLevel. They have been deprecated since 2022-04 and the field emailMarketingConsent should be used instead.

Learn more about the affected resources: - Customer object in GraphQL Queries. - CustomerInput object on GraphQL Mutations. - customer resource in REST. - customers/create, customers/delete, customers/disable, customers/enable, and customers/update webhook topics (https://shopify.dev/docs/api/admin-rest/2024-01/resources/webhook#event-topics).

Buy X Get Y discounts now support setting a fixed amount discount. This new option can be utilized alongside the existing percentage or free item discount options for a minimum qualifying purchase.

Use this option to create promotions such as “Buy 2 items, get $20 off”. This option is available as both an automatic discount or a discount code using the Discounts GraphQL API.

For more details on how to implement this new feature, refer to our API Guide in the Shopify Developer Documentation.

As of API version 2024-01, you can use the marketRegionsDelete mutation to delete multiple market regions in a single mutation.

Learn more about markets on Shopify.dev.

You can now add, remove, and update discounts to new or existing items when editing orders.

The orderEditAddLineItemDiscount mutation allows you to add a fixed amount or percentage discount to an already existing item during an order edit. Previously, this mutation was limited to applying discounts to new products or custom items added to the order.

In addition, two new mutations allow you to remove and update discounts. The mutation orderEditRemoveDiscount removes discounts on newly added, existing products, or custom items, while the orderEditUpdateDiscount mutation allows for updating discounts.

For more information about using discounts with order edits, visit the tutorial on editing an existing order with the Admin API.

We are introducing two new fields in the MetaobjectDefinition type: - createdByApp: The app used to create the metaobject definition. - createdByStaff: The staff member who created the metaobject definition.

Similarly, we are introducing two new fields in the Metaobject type: - createdByApp: The app used to create the object. - createdByStaff: The staff member who created the metaobject.

Additionally, we are deprecating the staffMember field in the Metaobject type. This field is being deprecated, and the createdByStaff field should be used instead.

Upcoming in API version 2024-01, access controls (access.storefront) are modified to be more explicit for custom data. These changes affect how reserved prefixes can be modified in the admin as well as how access controls are set by apps.

As a reminder, by default metafields and metaobjects are owned by Shopify and provide no restrictions to reading, writing, or modifying.

For app reserved prefixes, access is 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 the metafields will be publicly readable in the storefront surface area (Liquid templates and Storefront API).

Learn more about access controls for metafields and metaobjects respectively on Shopify.dev.

As of GraphQL Admin API version 2024-01, you can use the orderCancel mutation to cancel an order. The mutation allows apps to specify some options for cancellation (eg whether or not to refund the customer, restock inventory quantities, notify the customer) as well as a reason for cancellation and a merchant-facing staff note. The mutation performs cancellation asynchronously in a background job and as such, returns a job that can be queried for using the job API

AWAITING_RETURN_ITEMS The fulfillment hold is applied because of return items not yet received during an exchange.

The new hold reason is applied to a fulfillment hold on a fulfillment order when a return is created with exchange items.

As of API Version 2024-01 we've added a few extra documentation details around our recent Split and Merge feature.

• Webhooks for Split and Merge are now available.
• FulfillmentOrderLocationForMove has had the availableLineItems and unavailableLineItems connections added along with a count of each.
  
• A new error code No Line Items Provided To Split has also been added.

As of REST and GraphQL API Version 2024-01 we have added more information to the FulfillmentOrder and FulfillmentOrderLineItem objects.

We've added the following fields to the FulfillmentOrder graphQL object: orderId, orderName, orderProcessedAt, channelId.

With this change, order information required to fulfill an order is accessible on the fulfillmentOrder object with any of the fulfillment_orders access scopes. The same data is available via fulfillmentOrder.order, but this requires read_orders access scope.

Additionally we've added the financialSummaries field to the FulfillmentOrderLineItem graphQL object. Within this field you have access to these subfields: approximateDiscountedUnitPriceSet, discountAllocations, originalUnitPriceSet and quantity. However, the quantity value on the FulfillmentOrderLineItem.financialSummaries reflects the quantity with respect to the FulfillmentOrderLineItem. The same data is available via the REST api when the query parameter include_financial_summaries=true is sent with the request.

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

Learn more about FulfillmentOrder on Shopify.dev and FulfillmentOrderLineItem on Shopify.dev.

As of API version 2024-01 of the GraphQL Admin API, your app can subscribe to metaobjects/create, metaobjects/update and metaobjects/delete.

These new webhook topics use sub-topics so you can subscribe to events for the specific types of metaobjects your app cares about. Learn more about sub-topics on Shopify.dev

As of the 2024-01 release of the GraphQL Admin API, you can update the status field of a subscription contract in a single operation with the subscriptionContractActivate, subscriptionContractPause, subscriptionContractCancel, subscriptionContractFail, subscriptionContractExpire mutations.

As of the 2024-01 release of the GraphQL Customer API, you can update the status field of a subscription contract in a single operation with the subscriptionContractActivate, subscriptionContractCancel and subscriptionContractPause mutations.

As of the 2024-01 release of the GraphQL Admin API and GraphQL Customer API, you can update the skipped field of a subscription billing cycle in a single operation with the subscriptionBillingCycleSkip and subscriptionBillingCycleUnskip mutations

As of the 2024-01 release of the GraphQL Admin API, new dedicated webhook topics have been introduced to notify whenever there is a change in the status of a subscription contract.

The topic subscription_contracts/activate is added when the subscription contract status turns to active, subscription_contracts/expire when a subscription contract's status turns to expire, subscription_contracts/fail when the status turns to failed, subscription_contracts/cancel when the status turns to cancelled, and subscription_contracts/pause when the status turns to paused.

More information on webhooks can be found here

As of Admin GraphQL 2024-01, the SubscriptionContractSubscriptionStatus.STALE status is being deprecated. Instead, please use EXPIRED or CANCELLED.

Any existing contracts with the STALE status will be returned as CANCELLED.

Additionally, we are now preventing the update of Subscription Contracts to have the STALE status.

As of the 2024-01 release of the GraphQL Customer API, you can fetch the available delivery options for a subscription contract with subscriptionContractFetchDeliveryOptions. And you can select an option from a delivery options result and update the delivery method on a subscription contract with the subscriptionContractSelectDeliveryMethod mutation.

As of the 2024-01 release of the GraphQL Admin API, the SubscriptionBillingAttemptCreate mutation now prevents the creation of Billing Attempts if a subscription contract has a terminal status: 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 more about the Subscription Contracts API and Billing Attempts on Shopify.dev.

Using the TranslationsRegister GraphQL API, you can now register translations for Product types.

Product type filters will now be displayed to customers shopping in the store's non-default language.

Learn more about TranslatableResourceTypes on Shopify.dev.

As of API version 2024-01, you are now able to incorporate links to Metaobject pages as menu items in your Storefront Menus. Please note that only Metaobjects with both Renderable and OnlineStore capabilities enabled are eligible for Online Store URLs.

Learn more about Metaobject Pages on shopify.dev

As of Storefront API's 2024-04 release, you can use buyerIdentity.deliveryAddressPreferences.deliveryAddressValidationStrategy (accepted values STRICT or COUNTRY_CODE_ONLY) to enable address validation on the passed deliveryAddress for any cart mutations that accept a buyer identity as input (like cartCreateor cartBuyerIdentityUpdate).

Passing STRICT will perform a full validation on the address fields, and will raise CartUserErrors for invalid addresses. Invalid addresses will not be stored on the cart.

Passing COUNTRY_CODE_ONLY or omitting the field will only validate the presence of a valid country in the address (unchanged behavior from previous version).

The richtext, text, and inline_text settings in the theme editor are now compatible with text fields of metaobject reference lists. For example, merchants can now create a list of product materials on a product detail page via the richtext setting using dynamic sources.

This includes updates to the metafield_tag and metafield_text Liquid filters to support metaobject reference metafields. For example: {{ product.metafields.custom.authors | metafield_text: field: "name" }} will output an author's name. More information on the liquid implementation can be found on the dynamic sources docs.

As of the 2024-01 version of the Admin GraphQL API, you can filter the prices connection on Price List using a query param with supported product_id and variant_id filters.

Learn more about the Price List API on Shopify.dev.

With the latest version of App Bridge, you can use the modal API with custom DOM content.

You can also use the new max modal variant. This is the replacement for the previous Fullscreen API. Learn more about it in the documentation.

As of API Version 2024-01, the Shipping Discount Function API will be available to use on all merchant stores.

This Discount Function API can be used for use cases such as:

• Discounting specific delivery options (e.g. Free standard shipping only)
• Discounting shipping based on contents of cart (e.g. Buy this candle and get free shipping)
• Discounting shipping based on buyer identity, how many orders they’ve placed, etc.
  

Please note that the discountApplicationStrategy on FunctionRunResult (and its predecessor, FunctionResult field) is being deprecated, and removed in 2024-01.

You can learn more about the Shipping Discount Function API here.

As of GraphQL Admin API version 2024-01 , you can use the ID field to identify an InventoryQuantity object. This object now implements Node interface.

We’ve unlocked the ability for partners to add unique and powerful functionality to the customer account experience by building extensions directly into new customer accounts.

Starting today, customer accounts extensibility is now available in developer preview, allowing partners to build extensions on new customer account pages (such as the order index, order status and customer profile pages), add highly visible order actions and create full-page extensions tailored to specific merchant needs.

Join us in creating better buying experiences, where customers navigate seamlessly across apps, with one single login.

Start building today

Get started by reading our developer documentation and join us on Discord December 14, 2023 at 1pm EST.

Breaking change: UI extensions on versions 2023-10 or older that use either the purchase.checkout.shipping-option-list.render-before or the purchase.checkout.shipping-option-list.render-after will no longer render if the checkout contains both a one time purchase and subscription item.

As of 2024-01, purchase.checkout.shipping-option-list.render-before and purchase.checkout.shipping-option-list.render-after will be duplicated for possible types of delivery groups (One Time Purchase and Subscription). You can use the new ShippingOptionListApi to target each delivery group in your extension.

The delivery group the extension is attached to will be passed as a target. In React, you can also use the useDeliveryGroupTarget() hook to retrieve the current delivery group. The target will be undefined if the group is not available, for example when the buyer hasn’t entered an address on One-page checkout, or when shipping is unavailable for this address.

We’re also introducing a new unique id on a DeliveryGroup to identify each delivery group.

If your extension is capturing buyer inputs at Checkout and storing the information in a metafield, you can use checkout attributes with a namespaced key to capture information for multiple delivery groups rendered on Checkout. See examples.

These changes can be tested today using the Checkout Extensibility developer preview using the unstable api version.

Learn more about these API changes on shopify.dev

As of December 6th, 2023, Automatic Discounts created using Shopify Functions will apply by default to B2B customers. Previously, it wasn't possible to target B2B customers with discounts. Discount codes created using Shopify Functions are also available, but gated behind a beta flag, so merchants will need to explicitly opt-in for their store.

App developers can use the BuyerIdentity.purchasingCompany attribute on the Cart input to detect a B2B customer, and use that to customize the discount behavior for a merchant’s B2B audience. Examples of this could include:

• a discount that applies to B2B customers only
• a discount that applies to a specific B2B company only
• a discount that applies to D2C customers only

Note: at this time, discounts are not compatible for B2B customers configured to Submit all orders as drafts for review.

As of 2024-01, fields returning a "handle" will use an appropriate Handle scalar as their type, instead of a String. This signals that this type is not just any string, but specifically a handle. This specificity will help prevent bugs that could be caused by unexpected data.

Partners currently using refund line items to calculate a line item’s current quantity should migrate to using the new currentquantity field as it is a more reliable method. We recommend migrating to GraphQL as a general practice, however the currentquantity field has been added to indicate a line item’s current quantity after removals as of Admin REST API version 2024-01.

Learn more about the Order.line_items object on Shopify.dev.

Partners must now obtain a unique code to initiate a collaborator request and access a merchant’s store.

Collaborator request codes, previously optional, are now enabled by default for all merchants. This change gives merchants more control over who can access their store as collaborators, by ensuring that only those with the unique code can send a collaborator request.

Learn more about collaborator requests in the Shopify Help Center.

As of release candidate API version 2024-01, the schema for the Customer Account API has evolved significantly resulting in breaking changes. This update is necessary to ensure a more streamlined developer experience. Support has also been added to redirect buyers to a specific URI after logout with the post_logout_redirect_uri query parameter, providing a solution for custom storefronts with multiple domains. Additionally, mutations for modifying marketing subscriptions have been added with customerEmailMarketingSubscribe and customerEmailMarketingUnsubscribe. The Customer Account API is available in Developer Preview and accessible via the Hydrogen and Headless channels. We encourage developers to provide feedback to help shape future iterations of this API.

Learn more about the schema updates and the new features in the developer documentation.

We’ve introduced dedicated webhook topics that will be sent out whenever a discount has been created, updated or deleted, enabling developers to keep their discount apps in sync.

Learn more here

As of GraphQL Admin API version 2024-01, we are excited to introduce the Customer Data Erasure API. This API allows merchants to handle customer data erasure requests in compliance with GDPR, CCPA, and other data protection regulations. The API includes two new mutations:

• customerRequestDataErasure enqueues a request to erase customer's data.
• customerCancelDataErasure cancels a pending erasure of a customer's data.

To learn more about how data erasure is processed and the impact on customer data, please refer to the Shopify Help Center.

All Shopify Functions executions are now visible for production stores in your Partner Dashboard.

Run details are only available for failed runs that have been shared by users.

More information can be found on Shopify.dev:

• Testing and debugging practices for Shopify Functions
• Shopify Functions error handling

As of Admin API 2024-01, AppSubscriptionDiscountInput.durationLimitInIntervals will no longer accept 0. To create a discount with an unlimited duration, durationLimitInIntervals should not be provided.

Shopify’s Checkout Kit for Android enables you to provide the world’s highest converting, customizable, one-page checkout directly within a mobile app. The presented experience is a fully-featured checkout that preserves all of the store customizations: Checkout UI extensions, Scripts, Functions, Web Pixels, and more. It also provides platform idiomatic defaults such as support for light and dark mode, and convenient APIs to embed, customize, and follow the lifecycle of the checkout experience.

Today we are launching Developer Preview of the Mobile Kit for Android, as a follow up to our iOS deverloper preview launch on October 19th.

More information can be found in our blog post as well as in the Github repository.

As of GraphQL Admin API version 2024-01, we are removing the deprecated imageId and imageSrc fields from the ProductVariantsInput input object. Please use the mediaId and mediaSrc fields instead.

Learn more about the usage of the media fields on Shopify.dev

As of 2023-11-07, Checkout Extensibility on the Thank you and Order status pages is available to plus merchants. Merchants can now make code-free, app-based, upgrade-safe customizations throughout the buying journey to create holistic and consistent experiences.

Checkout Extensibility replaces checkout.liquid, apps with script tags and additional scripts on the Thank you and Order status pages.

Script tags, additional scripts and checkout.liquid on the Thank you and Order status pages are now deprecated. Merchants have been notified of the following turn off dates: * August 13, 2024 - the removal date of checkout.liquid for in-checkout pages * August 28, 2025 - the removal date of checkout.liquid, apps with script tags and additional scripts on the thank you and order status page

Shops that aren't upgraded during these dates will be upgraded to an un-customized out-of-the-box Shopify Checkout.

The Storefront API Cart now returns a new key param appended to CheckoutUrl that is required to render buyer information in checkout. This behavior is applied retroactively to all versions of the Storefront API.

The param is validated and removed as the buyer is navigated into checkout. This change is transparent to the buyer and does not affect what they see in the browser or their ability to copy and share checkout URLs. When a checkout is loaded without the valid key, the cart is cloned, and buyer information is removed.

Example Format: https://example-shop.com/cart/c/c1-09av29f248bb6420de3842b051f6a1a3?key=824bdj25mhg1242bdb385

Action Required: If your app is manually constructing checkout URLs from cart IDs, you need to switch and use cart.checkoutUrl. If you’re augmenting the cart.checkoutUrl with additional parameters, update and validate that your code does not override the parameter and returns a valid destination URL.

We’ve added visibility into the theme install event itself as part of our existing integration with Google Analytics.

In addition to having full visibility into the theme install event, you can also now tie the theme install event to a Shop ID, enabling richer insights on the type of merchants that are installing your theme.

Learn more on our blog and shopify.dev.

We've added a new cleanup process for Subscription Contracts.

This process involves automatically canceling any Subscription Contracts owned by the subscription app that have not been terminated. These contracts may be in the active, paused, or failed status. The cancellation will occur 48 hours after a user uninstalls the app.

This is aligned with our purchase options cleanup process.

Previously, the Cart Transform API enabled functions to expand a single cart line item to form a bundle of components or add-on products, or merge multiple cart lines into a single line that represents a bundle.

With this release, update operations will also allow you to override the price, title, and/or image of a given line item. This gives you more more flexibility to make additional customizations to items in the cart.

More information can be found in the Cart Transform API developer preview documentation.

Hydrogen v2023.10 is now available. This release includes a number of new features and breaking changes.

Remix 2.0 (breaking change)

• Hydrogen 2023.10 now uses Remix 2.
• Remix has also been made a peer dependency, so you can keep your Remix package updated independently of Hydrogen.

Other breaking changes

• Hydrogen's default caching strategy has been updated to have a longer stale-while-revalidate period.
• A dependency bump for @graphql-codegen/typescript to v4 will require updates to Scalar types if you import them directly from Hydrogen or Hydrogen React.

Other changes

• All packages and examples now query v2023-10 API versions.
• Hydrogen now includes an API client for the Customer Account API.
• Custom cart methods are now stable.
• The GraphiQL client available through the local development server now includes the GraphiQL Explorer plugin, which makes it easier to browse GraphQL resources.
• Props and parameters that were deprecated in v2023-07 have been removed.
• Additional dependency bumps, patches, and fixes.

We're changing how payments are processed on POS in order to bring order cancellations to POS. These changes will go into effect beginning October 31, 2023 for POS Pro and January 22, 2024 for Shopify Plus.

Payments may be authorized for up to 15 minutes before being captured automatically or voided by retail staff. As such, you may notice a few changes to the Admin and Storefront APIs.

On the Admin API, you may see:

• AUTHORIZED as the OrderDisplayFinancialStatus for up to 15 minutes before transitioning to PAID. The status will transition to VOIDED if the order gets canceled within these 15 minutes.
• Separate OrderTransaction objects with AUTHORIZATION and CAPTURE as the OrderTransactionKind when the payment is authorized and captured, instead of a single transaction with the SALE kind.
• Separate OrderTransaction objects with AUTHORIZATION and VOID as the OrderTransactionKind when the payment is authorized and voided.
• An empty array for SuggestedRefund.suggestedTransactions until payments in the order have been captured.

On the Storefront API, the OrderFinancialStatus will exhibit the same behavior as the OrderDisplayFinancialStatus on the Admin API.

Learn more about canceling orders on POS here.

Learn more about OrderDisplayFinancialStatus, OrderTransactionKind, and SuggestedRefund on Shopify.dev.

As of GraphQL Admin API version 2024-01, we're deprecating the images field from the ProductInput input object and replacing it with a media argument in the productCreate and productUpdate mutations.

Learn more about the usage of the media field on Shopify.dev

As of 2023-10-24, the order status page is getting a new look with updated visual treatment that is consistent with new customer accounts. This change will be rolling out progressively to all developer shops on checkout extensibility developer preview to ensure a smooth transition.

To view this change in developer shops on the checkout extensibility developer preview, navigate to Settings > Checkout > Customize and select Order Status from the page dropdown.

No action is required and there should be no changes to any UI extensions in development.

Learn more about UI extensions on the thank you and order status pages on Shopify.dev.

We've added the available_languages, continent and popular? properties on the country object in Liquid.

You can now access the languages that have been added to the market that a country belongs to, the country's translated continent name, and whether the country is a popular one amongst those that the shop sells to.

These properties provide flexibility when building a localization switcher, allowing customers to switch country and language simultaneously and allowing for grouping or sorting countries in a theme's country selector

Learn more about these new fields in the dev docs.