Developer changelog

As of Admin GraphQL API 2024-04, there will be new fields exposed on InventoryItem (and related input types) and some fields on ProductVariant (and related input types) that were marked as deprecated.

For InventoryItem and related input types:

• InventoryItemMeasurement and InventoryItemMeasurementInput were added as new types, with a single field: weight (which is a Weight type).
• measurement was added as a field to InventoryItem.
• harmonizedSystemCode, measurement, and requiresShipping were all added as input fields to InventoryItemInput.

For ProductVariant and related input types:

• fulfillmentServiceEditable, weight, and weightUnit were all marked as deprecated on ProductVariant.
• harmonizedSystemCode, requiresShipping, weight, and weightUnit were all marked as deprecated on ProductVariantInput and ProductVariantBulkInput.

These changes are all in support of removing long-deprecated fields on ProductVariant and removing the duplicated fields between ProductVariant and InventoryItem.

Developers can now generate even more demand for their apps by showcasing them on the category and subcategory pages of the Shopify App Store.

Learn more about category page ads on Shopify.dev.

As of 2024-04, you can filter the results returned by the Product.media connection to a specific media_type.

Using the Product.media connection enables you to retrieve all the media that's associated with a product including images, video, and 3D models or filtering to a specific media_type such as IMAGE. We recommend that developers migrate their apps from the Product.images connection to Product.media.

As of GraphQL Admin API version 2024-04, you can add new shipping lines or remove existing shipping lines when editing an order. You can also continue to query removed shipping lines.

The mutation orderEditAddShippingLine allows you to add a new, custom shipping line to an existing order. The mutation orderEditRemoveShippingLine allows you to remove existing shipping lines from an order. The mutation orderEditUpdateShippingLine allows you to update the attributes of a newly added shipping line before committing the order edit. The new field shippingLine.isRemoved allows you to determine whether a shipping line has been removed. The new parameter includeRemovals on the connection order.shippingLines allows you to query removed shipping lines. The default value for this parameter is false, so removed shipping lines will not be returned by default.

For REST API users, removed shipping lines will continue to be returned in the payload of the Order resource. As of API version 2024-04, you can determine whether a shipping line has been removed by checking the value of the new attribute is_removed.

For consumers of Order webhooks, removed shipping lines will also continue to be returned in the payload. As of API version 2024-04, the payload for shipping lines will have a new key is_removed. You can consume the order/edit webhook to be notified when shipping lines have been added or removed from an order.

For more information about editing shipping lines, visit the tutorial on editing an existing order with the Admin API.

As of 2024-04, you can now query the OrderPaymentStatus object to obtain information about its corresponding transactions.

As of 2024-04, you can specify custom amounts to be charged from a vaulted card through the OrderCreateMandatePayment mutation for Shopify Plus merchants.

As of version 2024-04 of the Admin GraphQL API, you can now void a transaction through the transactionVoid mutation.

The @defer directive is now available in developer preview, allowing developers to prioritize part of a GraphQL query without having to make multiple requests to fetch the remaining information. Clients can make a single request and data will be received in a stream of responses.

This developer preview will guide our decision on the inclusion of this directive in the Storefront API. It will also provide insights into whether clients can effectively support the @defer directive in their implementations, as we are planning the introduction of fields that require mandatory use of @defer.

Test out the defer directive today by enabling the developer preview and following our tutorial . We value your input, please share your feedback on Github.

React developers can start using the App Bridge React v4 via NPM. This optional NPM package works with the required App Bridge library loaded via the <script> tag.

For those already using App Bridge React v3 or lower, please refer to the migration guide for how to upgrade.

As of the 2024-04 version of the GraphQL Admin API, you can use the new argument withCodeDiscounts on the order.lineItem.discountedTotalSet field to include or exclude line item discounts originating from a discount code. The current behaviour of discountedTotalSet is to exclude code based discounts and as such, the default value for this option is false so there will be no change required for clients who want to continue to have them excluded.

See the documentation for discountedTotalSet on Shopify.dev. The argument is already available on the unstable Admin API.

As of February 20, 2024, the returnCreate mutation and the returnApproveRequest mutation will create return sales on the order. Each returned item will create a product type return sale. Previously, these mutations did not create sales.

This new behavior is applied to all non-Plus merchants, and Plus merchants who have enabled Exchanges capabilities using Test Drive. Learn more about feature test drives in our Shopify help docs

To keep track of line item or value changes to the order due to returns, we will soon provide more information on subscribing to enhanced Return related webhooks. Stay tuned for these details.

Related changes

Return fees as RETURN type

When a merchant adds return fees to a return using the admin, return fees will show up as a RETURN OrderActionType on a SalesAgreement.

LineItem.currentQuantity and LineItem.refundableQuantity definition changes

Previously, both LineItem.currentQuantity and LineItem.refundableQuantity returned identical numbers. They represented the total quantity of the line item minus the quantity that had been removed.

The definitions of these properties have been updated:
- LineItem.currentQuantity: This property now considers returns that are in progress, even if they haven't been refunded yet. CurrentQuantity will now be the line item's total quantity minus the removed or returned quantity.
- LineItem.refundableQuantity: It now represents the line item's total quantity minus the refunded quantity, not the removed quantity. This indicates the quantity of line items that are available for a refund, including items in a return.

These changes affect all currently supported APIs (GraphQL, REST, liquid, etc.)

Use ReturnRefund when refunding a return line

Use the returnRefundGraphQL mutation when refunding a line item on a return to guarantee accurate sales ledger entries. We strongly encourage developers to migrate away from using refundCreate and POST refund to refund return line items due to potential inaccuracies in the sales ledger due to both returns and refunds producing product type return sales.

As of February 15, we added the following updates to POS UI Extensions:

• Added optional bannerProps to the CameraScanner component, which allows the UI extension to surface banners within the context of the CameraScanner.
• Added fetchPaginatedProductVariantsWithProductId to the ProductSearch API, which allows the UI extension to fetch pages of variants for a product by ID.

All of the changes are available for POS UI extensions version 1.6.0 and POS app version 9.2.0. See the version log for all version details.

Product duplication now includes variant metafields. Previously, variant metafields were ignored when products were duplicated. Products can be duplicated via admin or GraphQL

Starting from April 2024, the Order risk REST and GraphQL APIs are deprecated:

• admin-rest / order-risk
• admin-graphql / field-order-risks
• admin-graphql / field-order-riskLevel

Clients are advised to use the new Risk Assessments API instead:

To create assessments, you can now use the new mutation orderRiskAssessmentCreate.

Additionally, a new webhook topic is available: ORDERSRISKASSESSMENT_CHANGED

As of version 2024-04 of the Admin GraphQL API, you can read the additionalInformation object value on the deliveryMethod object using the fulfillmentOrder query .

Learn more about additionalInformation argument on Shopify.dev.

Help merchants with post-purchase customer service by enabling them to issue, track, and report accurately on store credit using Shopify’s new Store Credit Primitive and API, available in developer preview.

Streamline checkout, customer support and workflows, with a single, reloadable store credit balance for customers. Start using the store credit GraphQL API today to add key functionality that enables differentiation between gift cards and store credit, the linking of store credit directly to a sole customer, and more.

Get started

We've introduced OAuth2 Token Exchange and Shopify managed install to eliminate screen flickering due to full page redirects on app load and provide uninterrupted & faster embedded app loading and installs.

To avoid unnecessary redirects and page flickers during the app installation process, configure your app's required access scopes using Shopify CLI. This allows Shopify to manage the installation process for you.

OAuth2 Token Exchange allows embedded apps to exchange session tokens for access tokens. This avoids the multiple requests and redirects as a result of OAuth authorization code grant, making it easier to retrieve both online and offline access tokens.

Use Shopify CLI to generate a starter app, which uses token exchange and leverages Shopify managed install. For existing Remix apps, please refer to our migration guide.

You can now use Admin UI extensions to provide a user interface for merchants to configure your Cart and Checkout Validation Functions.

Additionally, merchants on any plan can now use validation functions provided by public apps distributed through the Shopify App Store.

Learn more on Shopify.dev.

The Checkout Branding API now supports container styling for sections in the main and the order summary areas of checkout. This change is available in the 2024-04 release candidate.

These changes will give merchants more control over section corner radius, border styles, color scheme, spacing and shadow customizations within or between sections. We will be releasing an update to customize the header and footer sections in a subsequent release.

Learn more through our reference documentation.

As of 2024-01-31, Checkout Extensibility enables merchants to customize checkout's header and footer with their brand and navigation intent.

Use the GraphQL Admin API's checkout branding to: * Hide the logo, breadcrumbs, default footer content, and Back to cart links * Control the footer position and alignment

Use checkout UI extensions to add content and replace hidden content, with the new header and footer extension targets in Checkout and the Thank you page.

Learn more on Shopify.dev.

You can now use the Discounts Allocator Function API in Developer Preview to implement custom logic for distributing discounts across multiple products or orders.

This new API allows you to define your own logic for how discounts are distributed, enabling the implementation of merchant-specific discount strategies.

Learn more about the Discounts Allocator Function API in our developer documentation.

Theme Check 2.0 marks the grand unification of Shopify theme developer tools. Now, you can use all Language Server Protocol (LSP) features in the admin code editor, on the Shopify Liquid VS Code extension, and on Shopify CLI.

Here's what's now available everywhere:

• Hover documentation support
• Code completion for theme, section, and block settings
• Code completion for theme translations
• Code completion for HTML tags, attributes, and values
• Code completion for Liquid filters, objects, and tags
• Enhanced auto-closing pair user experience
• Automatic support for new Liquid tags, filters, and objects

We're excited to see how these changes will enhance your theme development process. Learn more about Theme Check 2.0 on Shopify.dev and happy coding!

You can now subscribe to select DOM events with the Web Pixels API, including input_changed, input_blurred, input_focused, form_submitted, and clicked.

These new events will help merchants better understand how visitors are engaging with their online stores.

Learn more about Web Pixels on Shopify.dev.

With the latest release, Hydrogen and Oxygen make the path to production more seamless than ever. We’ve added new developer tools so you can more easily debug and optimize your build before you deploy:

• Subrequest profiler: get a more detailed look at what’s happening inside your Remix loaders — identify query waterfalls, inefficient API calls, and suboptimal caching behavior.
• Error console: stack-trace errors back to your source code, right from the Shopify admin, so you can get right to the fix.
• CLI deploys: Deploying to Oxygen is easier than ever. Run the new deploy command to create deployments from your local dev environment, or build your own CI/CD processes on any platform.
• End-to-end testing support: Automatically and securely run E2E tools like Playwright or Cypress on every Oxygen deployment with our new E2E testing tokens.
• Shareable storefront previews: Share progress with colleagues and stakeholders — even if they don’t have access to your Shopify Admin — with our new revocable, token-based shareable links.
• Runtime mirroring: Hydrogen’s development server runtime is now nearly identical to production Oxygen, and now serves assets from a separate domain to better replicate how Shopify’s CDN works.
• Bundle insights: analyze your worker bundle file to find bloated dependencies, optimize your bundle size, and reduce cold start times, so your app stays fast over time.
• CLI upgrade command: Stay up-to-date with the latest version of Hydrogen and Remix with h2 upgrade command from your CLI. Your project’s critical dependencies will all be updated to the latest version, along with a custom migration guide.
• It’s easier than ever to learn Hydrogen, with our refreshed docs, and a new suite of examples.

Learn more about our latest release in detail.

You can now integrate the Customer Privacy API and the Shopify Privacy & Compliance app into your Hydrogen storefront, making it easier to comply with data protection laws and increase customer trust. This allows consent to flow to Shopify so it can be honored on Pixels, Checkout and other services.

The Shopify App Store is introducing structured app category details to make it even easier for merchants to evaluate relevant apps within the same category. Starting today, category details can be added for apps classified under:

• Product reviews
• Dropshipping
• Product bundles
• Subscriptions
• Loyalty and rewards
• SEO
• Page builder
• Pop-ups
• Discounts
• Email marketing

Using this structured data, merchants will soon be able to see this information on the app details page, as well as on the compare apps page

Learn more about how App Category Details work at shopify.dev

When you define the permissions your app requests, they will now show up in a new "Data Access" section on your app details page to help build merchant trust.

Your installation flow will also be updated to a new installation modal, rather than a full page experience, which will streamline the install process for merchants.

Shopify’s Checkout Sheet Kit enables you to provide the world’s highest converting, customizable, one-page checkout directly within a mobile app. Today we are happy to announce that the v1.0.0 of Checkout Sheet Kit for Android, React Native and Swift is officially available and no longer in developer preview. The libraries are open-source and ready for you to start building.

More information can be found in documentation as well as in the Github repositories linked above.

Now in developer preview, we’ve introduced new GraphQL product APIs that support 2000 variants, allowing for support of more complex catalogs.

Learn more here.

Merchants can now discover your app in the new AI-powered guided search that supports merchant’s natural language queries, and provides insights to help them make a better informed app decision. This can be accessed through the search bar in the Shopify App Store under the "Ask about apps" section. Keep your listing accurate and up-to-date with the solution that you provide to help the right merchants find your app.

Try it now

An upcoming release affects the app configuration deployment process using Shopify CLI, which includes breaking changes that require your attention.

Effective January 31, 2024, we're introducing an improved way to release your app configuration and extensions together using the shopify app deploy command. With this update, you can version and roll back changes to your app configuration as part of app versions!

Upcoming Breaking Change Details: The Shopify CLI shopify app config push command will no longer be supported in any CLI version. Instead, you should use the shopify app deploy command to release your app configurations and extensions.

Next steps starting January 31, 2024:

• Developers using shopify app config push to release app configuration need to update to the latest Shopify CLI version and use shopify app deploy instead.
• Developers using shopify app config push in CI/CD workflows need to update their deployment scripts to remove this command.

Detailed migration instructions will be provided in app configuration documentation at the time of release on January 31.

You can now subscribe to compliance topics using you app's TOML configuration file and use PubSub or Eventbridge URIs as your subscription endpoint.

Learn more about mandatory compliance topics here.

We've introduced the following changes to improve and update the App Design Guidelines:

• The full-screen mode guidance has been revised and renamed to max modal.
• The admin app block directive regarding the summary property has been removed as it is no longer applicable.

With the latest version of App Bridge, you can use the POS API. This provides the ability to retrieve the POS user, device, and location data, while also interacting with the cart and closing the app.

As of 2024-04, the Abandonment.isFromCustomStorefront field has been released into stable version.

In preparation for supporting IPv6 on storefront domains, merchants and partners should update any third-party tools, such as firewall rules, to allow traffic in the CIDR range 2620:127:f00f::/48 and 2620:127:f00e::/48 by January 16, 2024.

Outbound traffic from Shopify will not be affected.

As of version 2024-01, you can use the GraphQL Admin API to get and set a firstName and lastName on the CompanyAddress.

As of 2024-04 the following fields on the MarketWebPresence object will no longer return locale strings and will instead make use of the ShopLocale type:

• defaultLocale
• alternateLocales

We’re making this change as it allows callers to query for more information regarding locales on a market, such as whether it is published or primary. Please ensure to update your API calls using MarketWebPresence.defaultLocale or MarketWebPresence.alternateLocales to use the ShopLocale type.

Learn more about the MarketWebPresence object on Shopify.dev.

As of Shopify CLI version 3.53+, you can use GraphiQL in the CLI while running app dev by simply pressing the g hotkey.

This GraphiQL instance uses your app's credentials, working with the same data and access scopes, ensuring that what works in GraphiQL will work exactly the same in your app. We expect this feature to streamline how you create and edit GraphQL queries.

Learn more about in our documentation.

With the latest version of App Bridge, you can use the filter query option with the Resource Picker API to filter resources without showing the query in the Resource Picker search bar.

As of the 2024-01 version of the REST Order APIs, channel_liable field on the TaxLine has been updated to reflect the value indicated by the app. The behaviors now align between the REST and GraphQL endpoints.

The channel_liable field lets developers inform merchants that another party is responsible for sales tax remittance, which then helps merchants better understand the tax that they are responsible for.

channel_liable can contain the following values: - true indicates that the channel is responsible for remittance of the tax line - false indicates that the channel is not responsible for remittance of the tax line

If the channel_liable field is not populated, a value of false will be assumed.

As of API version 2024-01, we've added the CAPABILITY_VIOLATION error code to the MetafieldsSetUserErrorCode enum. This error code is returned if you attempt to update a metafield in a way that doesn't conform to the enabled capabilities.

Previously, the Cart Transform Function API allowed percentage based adjustments to the cost of a bundle when using expand operations. The weight price algorithm would then allocate the bundle price to its component lines based on the weight of each component line (unit price * quantity).

As of the 2024-01 Cart Transform Function API version, expand operations will also allow you to set fixed prices on each component of the bundle, resulting in a bundle price that is the sum of each component. Additionally, the expand operation will now allow you to define a custom title and image for each parent line item. This gives you more control over bundle pricing and enables bundles to be used for add-on products.

A new update operation will allow 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. The update operation is only available for Plus merchants.

To see what operations are available for a shop, you can query the cartTransform field on ShopFeatures.

Finally, the CartTransformCreate mutation in the Admin API now supports a blockOnFailure field that determines if cart and checkout operations should be blocked if the CartTransform function fails to run. This can be used as a safeguard if the Cart Transform is considered a critical component in resolving merchandise attributes (e.g. price, title, image).

More information can be found in the Cart Transform API documentation and the CartTransformCreate mutation.

As of 2024-01 version in the admin GraphQL API, you can specify whether to include translations when calling the productDuplicate mutation. When this optional argument is passed in as true, all translations that are saved on the product, its variants, and its metafields are copied over to the new product.

As of Admin API 2024-01, you can use the checkoutBrandingUpsert mutation to reset branding settings to their default state without resetting each leaf field explicitly. It is now possible to pass in 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.

Note that for all API versions, it is also possible to pass in a null value to a non-leaf subfield, for example design_system.colors.schemes.scheme1, to reset a given group of parameters.

Both of these changes enhance the usability of the Checkout Branding API by allowing to easily reset groups of branding parameters.

As of API version 2024-01, we fixed a bug that had allowed refunds specifically against a requested return. Refunds are blocked on returns with a REQUESTED status.

• Learn more about the status of a return on Shopify.dev.
• Learn more about requesting returns on Shopify.dev
• Learn more about self serve returns on the help center

As of the 2024-01 version, you can Schedule Changes to your inventory quantities. For example, if an application user creates a purchase order and adds some incoming quantities for a specified inventory item at a location, they can then create a Scheduled Change that states the date these quantities are expected to be transitioning from incoming to available.

This information can then be used for planning to help the merchant make better buying or selling decisions. It will not automatically change any quantities, that still has to be done using one of the existing quantities mutations for inventory such as InventoryAdjustQuantitites. As part of this change there will be a new mutation inventorySetScheduledChanges along with the scheduledChanges field on the InventoryLevel query model which will allow the merchant to access the Scheduled Changes for a specific item at a given location.

You can include links inline in the text, and add another link at the end in this format:

Learn more about Inventory Scheduled changes on Shopify.dev.

As of Admin API 2024-01, you can use the Checkout Branding API to customize the look of the ChoiceList components on your checkout with customizations.choiceList.

Learn more about the ChoiceList component on Shopify.dev.

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.