Developer changelog

As of API version 2024-07, you can use the url_parameter_value as a tracking parameter in the MarketingActivityCreate and MarketingActivityUpdate mutations. This feature is currently available on a limited basis to some partners only. UTMs should continue to be used for most partners' tracking parameters.

Additionally, MarketingActivityUserError will be the required type on the user_errors field for the MarketingEngagementCreate mutation. This will match the user_error types of the other mutations that belong to the Marketing Activity and Engagements API.

We've given listing pages a refreshing uplift to improve overall density and readability.

A sticky sidebar keeps important highlights and the Install app CTA always in merchants' view. We continue to roll out more support for structured features for more app categories, so we've adjusted this section to accommodate growth.

This listing update is entirely a front-end refresh to keep the browsing experience high-quality for our merchants. No listing functionality will be impacted.

As of version 2024-07 of the Admin GraphQL API, you can use the new ordersCount field to count the orders for a given shop.

Learn more about ordersCount on Shopify.dev.

As of Admin API 2024-07, Order object will expose the following new fields:

• staffMember
• sourceName

Learn more about Order GraphQL object on Shopify.dev

As of GraphQL Admin API 2024-07 version, you can make use of a new mutation to delete an order.

Learn more about orderDelete on Shopify.dev.

As of Admin GraphQL API version 2024-10, we're deprecating the ability to set the available quantity on the InventoryActivate GraphQL mutation for already active states. Moving forward, use the InventorySetQuantities GraphQL mutation instead. This change will take into full effect starting on the 2024-10 version of the Admin GraphQL API.

As of Storefront API version 2024-07, you will get a NOTE_TOO_LONG user error in cart mutations in case the note exceeds the maximum number of 5000 characters.

As of 2024-07, the admin and storefront fields of MetafieldAccessInput and MetafieldAccessUpdateInput will begin using dedicated input enum types - MetafieldAdminAccessInput and MetafieldStorefrontAccessInput.

Learn more about access controls for metafields on Shopify.dev.

Customize the address autocomplete provider in Shopify Checkout with the Address Autocomplete API. The Address Autocomplete API unlocks the ability for developers to replace the default provider of address suggestions in Shopify Checkout. This allows merchants who have upgraded to Checkout Extensibility to leverage a growing ecosystem of third-party apps that augment the address autocomplete experience.

API Reference

• purchase-address-autocomplete-suggest
• purchase-address-autocomplete-format-suggestion

Pre-select your app’s capabilities early in the submission process to get a simpler, personalized list of requirements. If your app review gets paused due to a blocking error, a clear summary of issues and a straightforward resubmission process will help you (and your app review) quickly get back on track.

We are rolling this out to English speaking partners first this week. For more information on app review, see our dev docs.

Apps can now trigger Shopify's marketing automations that use the Customer subscribed to email marketing trigger (welcome new subscriber, and welcome series) by integrating with the Customers API.

When developers provide consentUpdatedAt upon updating the email marketing consent for a customer, the trigger and associated marketing workflow will fire as long as consentUpdatedAt is within the last 24 hours.

This change allows standalone lead capture apps to connect seamlessly with the rest of Shopify’s marketing automation tools. Apps that also offer automations should make sure merchants are aware they should choose to automate welcome emails in one place, not both, to avoid duplicate messages.

Tax lines created as a result of tax exemptions on orders (typically have price=0) will now be returned in API responses. This includes cases when the order, customer or product variant have been marked to not collect taxes (i.e. when the "Charge taxes" or "Collect Tax" checkbox is set to false).

This change is being released to stores progressively, with a plan to fully release it by May 23, 2024. The change will affect orders on stores that have the feature and have the appropriate tax registrations set up for collecting taxes on those orders

As of 2024-04, you can use the preferences object in the Cart API to prefill a checkout session.

These changes help merchants streamline their checkout process for their customers by prefilling information such as the preferred delivery method and pickup location. This change is additive to the 2024-04 version.

Learn more about these new fields in the cartCreate reference page and the CartBuyerIdentity reference page

For more information, an updated tutorial is also available.

As of 2024-07, the Payment Customization API has two new features that give you better control over accelerated checkout methods: 1. Improved naming: the function input graph now has more descriptive and specific names for accelerated checkout methods. 2. Placement control: Shopify Plus merchants will also be able to pass an optional placements argument in the hide operation, allowing them to explicitly hide accelerated checkout methods from the first or last step of checkout independently.

To learn more about payment customization functions, please refer to the documentation.

UI extensions and web pixels for public or custom apps on the Thank you and Order status pages are now available to merchants on Basic, Shopify and Advanced plans. In tandem, merchants will also have access to the new checkout and accounts editor, an all-in-one place for making customizations.

Additional scripts and apps with script tags on the Thank you and Order status pages will be turned off with one year notice. These must be replaced with a compatible app from the Shopify App Store or rebuilt with UI extensions and web pixels.

As previously stated, customizations for the Thank you and Order status pages achieved using checkout.liquid, script tags, and additional scripts will be turned off for Plus merchants on August 28, 2025.

More information can be found in our developer documentation.

Shopify Plus merchants using Shopify Payments are able to partially capture authorizations more than once. However, sometimes you know that the capture you're about to perform will be the last one. To reflect this, the orderCapture mutation has been updated in the 2024-07 version to support a new finalCapture parameter.

When you know you're capturing an authorization for the last time, setting the finalCapture parameter to true will release any uncaptured funds back to your customer. Doing so is likely to increase customer satisfaction and decrease the risk of chargebacks.

See also:

• Shopify Payments now supports multiple payment captures for the same order
• Shopify Payments now supports multiple payment captures for the same order in Australia and Romania

For merchants not on the Shopify Plus plan, the finalCapture parameter will have no effect: these authorizations can only be captured once, and uncaptured funds are always returned immediately to the customer.

At the time of writing, the finalCapture parameter only applies to transactions made through Shopify Payments. When capturing authorizations processed through other gateways, finalCapture must either be omitted, or set to null.

When handling requests with exceptionally large quantities (exceeding 1,000,000), the update endpoint of the Carts API previously capped the value to 1,000,000 and returned a 200/OK status without notifying the user.

We have now modified this behavior. While the update endpoint will continue to limit the quantity to 1,000,000, it will also issue a 422/Unprocessable Entity status alerting the API users to the adjustment.

The endpoint will not perform any additional quantity checks against inventory levels; this aspect remains consistent with previous functionality.

It is now possible for apps to view the access field of metafield definitions they have access to but do not own. An AuthorizationError error was previously returned when accessing the field for definitions the app didn't have permissions to manage. Note that accessing the access.grants field still requires permissions to manage the definition and an error will be returned if accessing the field with insufficient permissions.

As of 2024-07, the admin and storefront fields of MetafieldAccess will also start returning values in more cases instead of null. Metafields that do not have associated access grants will return PUBLIC_READ_WRITE for admin access and LEGACY_LIQUID_ONLY for storefront. In addition, definitions that were created with a storefront access of NONE will start returning NONE instead of null. Finally, it will also now be possible to set PUBLIC_READ_WRITE as the admin access control.

Learn more about access controls for metafields on Shopify.dev.

Hydrogen v2024.4.2 is out today. The May 2024 Hydrogen release contains several new features and bug fixes including:

• Redeploys on Oxygen
• B2B Support
• Improved support for third party requests in the request profiler
• Improved HMR stability
• Node 21 compatibility
• Content security policy improvements
• Analytics improvements
• h2 upgrade command detects outdated devDependencies
• Codegen schema resolution fix
• cli-kit improvements

Check out our full Hydrogen May 2024 release blog post for more details. And please drop your comments, feedback, and suggestions in GitHub Discussions!

As of API version 2024-07, we've added the RESERVED_NAMESPACE_ORPHANED_METAFIELDS error code to the metafieldDefinitionDelete mutation. This error code is returned if you attempt to delete a definition in a reserved namespace without setting deleteAllAssociatedMetafields to true.

The cart cookie value for the Online Store now includes a key param. Not including the key param will result in the removal of buyer details and your updates will be applied to a newly generated cart. This behavior is applied retroactively to all themes.

This change is rolling out now, and enforcement will go into effect after a grace period of 1 week.

Example Format

• Before: value=c1-7a2abe82733a34e84aa472d57fb5c3c1
• After: value=c1-7a2abe82733a34e84aa472d57fb5c3c1?key=824bdj25mhg1242bdb385

Action Required

Provide the complete cart cookie value which includes the key param as well as the cart token.

Ensure that theme code is free from hard-coded assumptions (ex. Using regex to identify a cart token) on the format and structure of the cart cookie. This is especially critical if the cart cookie is manually constructed. If your theme utilizes the value set by default without modification, no action is needed.

You can now configure the customer privacy permissions and data sale settings for app pixels using the Web Pixel API. This will provide more insights by collecting events whenever the proper permissions are given by customers.

Learn more about Web Pixels on Shopify.dev.

You can now create visual filters with an image presentation. This allows developers and merchants to specify when filters are best displayed as detailed images instead of color and pattern swatches.

In the Liqudi API, we've added filter_value.image intended for better display support for icons, logos, and other detailed imagery. The filter_value.swatch is intended for color and pattern swatches.

Merchants must use Shopify's Search & Discovery app to set visual filters for their store.

As of Admin API and 2024-07 version, we're sunsetting ShopifyQL API. Use the Admin GraphQL APIs instead for extracting data for your use-cases.

For example, the Orders API, and the Web Pixels API should be useful starting points.

Now, theme developers can utilize schema translation files to make default values in theme sections translatable. This ensures that themes are equipped to support multiple languages right from the onboarding state and when integrating new sections. For detailed guidance on how to reference schema translations, please refer to the developer documentation.

As of version 2024-07, 3D Models and External Videos will be included in the GraphQL Admin Files Query.

As of version 2024-07 of the webhooks API, the includeFields that are specified on a webhook subscription will be available for all webhook topics.

As of version 2024-07 of the GraphQL Admin API, you can use the Metafield and MetafieldDefinition connections in the OnlineStoreArticle, OnlineStoreBlog, and OnlineStorePage objects.

Previously, you could only do this using the REST API.

As of GraphQL Admin API version 2024-07 the location field on the Order object has been removed. Use the retailLocation field instead.

Learn more about the Order object on Shopify.dev.

The GraphQL Admin API's DiscountEffectInput input object now includes an amount field. This change is backported to version 2024-01.

As of GraphQL Admin API version 2024-07, you can use the new retailLocation field on the Order object to query the physical location where a retail order is created or completed.

Learn more about the Order object on Shopify.dev.

Effective May 15, 2024, a maximum value of $2,000USD (or equivalent in global currencies) has been added to gift card issuance. All versions of the Gift Card API will respond with an error for issued gift cards that exceed $2,000USD (or equivalent in global currencies) after this date. The purchase limit for gift card products will be $10,000USD (or equivalent in global currency).

To help you and Shopify merchants stay within this limit, we’ve introduced a new Gift Card Limits query that returns the maximum value in any given currency.

This change will help keep Shopify merchants compliant with laws that apply to gift cards and help ensure they do not inadvertently violate them. The new maximum value will not affect gift cards issued before May 15, 2024.

Visit our Help Center for more information.

We are currently testing a feature that can halve load times for embedded Shopify apps using App Bridge via script tag and have found cases where apps break when they rely on an undocumented name="app-iframe" property to access their iframe

If your app uses the name="app-iframe" property to find its embedded app iframe, please either upgrade to App Bridge React v4 or reference the snippet below (gist here for reference) to avoid your app breaking in mid May when we begin rolling out these performance enhancements

The performance enhancement works by keeping multiple app iframes in the DOM at any given time. The name=”app-iframe” prop will no longer be unique

const APP_ID = ''; // accessible via window.shopify.config.apiKey


interface FrameList extends Window {
   [index: number]: Window;
}


function findAppFrameSafely(frameName: string) {
   if (window.parent) {
       const frames = window.parent.frames as FrameList;
       for (let i = 0; i < frames.length; i++) {
           const frame = frames[i];
           try {
               // referencing the name prop of a cross-origin frame will throw when there are multiple frames with the same name
               if (frame.name === frameName) {
                   return frame;
               }
           } catch (_) {
               // noOp
           }
       }
   }
}


const legacyFrameName_doNotUse = 'app-iframe';
const futureProofFrameName = `frame:${APP_ID}/main`;


const appFrame = findAppFrameSafely(legacyFrameName_doNotUse) || findAppFrameSafely(futureProofFrameName);


// continue doing whatever you were doing with the app's main frame
appFrame?.postMessage({}, window.location.origin);

• Where APP_ID is your app’s apiKey, either provided during config or accessible on window.shopify.config.apiKey
• Your app’s iframes are same-origin while other apps’ iframes will be cross origin. The try / catch finds only same-origin frames, in this case, your app’s iframe
• To be future proof, also use the unique name=”frame:${APP_ID}/main”. At the close of this project, app iframe names will be changed from the static name=”app-iframe” to a unique identifier pivoting on APP_ID. Please accommodate this new pattern now so your app doesn’t break when we update names!

As of Shopify CLI 3.59, commands have been unified under a single npm package and our recommended installation method is as a global npm package. This provides developers with a single installation and upgrade point for all development with Shopify CLI.

Dependencies for Shopify CLI are now bundled into the package as well, reducing installation time and potential conflicts with developer dependencies.

Existing use of Shopify CLI as a local dependency in app and Hydrogen projects is still supported.

Learn more about installation in the new centralized Shopify CLI documentation and learn about migrating your app to use a global installation.

Up to this point, you can send Inventory Item data in two places: through Product Variant mutations or on the InventoryItemUpdate mutation. Each of these places has a different input object type with very similar fields, with some keys showing up in one instead of the other.

As of Admin GraphQL API version 2024-07, these two input types are being unified. InventoryItemInput will now be the input object type on inventoryItemUpdate instead of InventoryItemUpdateInput.

At the same time the following fields were added on InventoryItemInput:

• sku
• countryHarmonizedSystemCodes
• countryCodeOfOrigin
• provinceCodeOfOrigin

Hydrogen v2024.4.0 is out today. The April 2024 Hydrogen release contains several new features:

• Built-in Shopify analytics with an improved developer experience and support for third-party services
• Vite support is now stable, providing hot-module reloading that’s up to 10 times faster
• Improved tooling for SEO
• env push command to bulk upload environment variables is now stable
• Customer Account API client to simplify authentication.
• SSL tunneling functionality in the CLI.

In addition to these new features, Hydrogen 2024.4.0 includes a range of updates, performance upgrades, and bug fixes.

Check out our full Hydrogen April 2024 release blog post for more details. And please drop your comments, feedback, and suggestions in GitHub Discussions!

As of version 2024-07 of the GraphQL Storefront API, Cart supports adding and querying for Gift Cards.

Updating Gift Cards can be achieved in two ways: - When creating a cart - adding the CartInput giftCardCodes property. - After a cart is created - performing the cartUpdateGiftCardCodes mutation.

You can also query the cart for applied Gift Cards using the appliedGiftCards property.

As of version 2024-07 of the GraphQL Admin API, DraftOrderInput now accepts discountCodes and acceptAutomaticDiscounts. These optional input fields will allow you to apply discount codes to a draft order and decide whether or not to accept automatic discounts during calculation.

Additionally, a new type field named DraftOrderPlatformDiscount has been added that describes details about how the platfom discount has been allocated across the draft order line items, the discount type, its name, and more.

Learn more about DraftOrderPlatformDiscount on Shopify.dev

We have released a feature for Plus merchants who

• Use products to represent additional fees or charges in checkout
• Are currently using checkout.liquid to customize the order summary
• Need a solution to continue doing so with checkout extensibility

Log into the Help Centre to connect with Plus Support who can assist with requesting access for eligible Plus Merchants

In version 2024-04 of the GraphQL Admin API, we exposed the cash tracking sessions that are created by Shopify POS. As of version 2024-07, you can use the API to query the cash transactions that are associated with each cash tracking session. The new cashTransactions connection returns all of the cash order transactions that affected the amount in the cash drawer during a cash tracking session.

To learn more, see CashTrackingSession (cashTransactions) in the GraphQL Admin API reference.

CartDiscountCode#code has been corrected to be case insensitive. For example, providing the input ["DISCOUNT", "dIsCoUnT", "discount"] on cartCreate or cartDiscountCodeUpdate will return a cart payload with one CartDiscountCode with the code value set to DISCOUNT.

You can now seamlessly integrate your app using admin action extensions at many more locations in the Shopify admin. These include draft orders pages, abandoned checkouts pages, and variant pages. You can find the full list of targets in the admin extension targets API reference.

Learn how to create your first admin action extension on Shopify.dev.

As of version 2024-04 the Storefront API field Cart.cartCost.checkoutChargeAmount will now return an estimated amount before taxes and discounts. In previous versions Cart.cartCost.checkoutChargeAmount was incorrectly returning the discounted cost.

We've added preloading of the Validation record and its metafields so that you can access them without the need of a fetch call. The Validation API will be gated by a new read_validations access scope in the near future, so you need to migrate to this new format for your extension to continue to work or the fetch call will start failing.

Learn more about Cart and Checkout Validation configuration on Shopify.dev.

As of GraphQL Admin API version 2024-04, you can use the new sort options in fulfillmentOrders query.

• createdAt: The date that the fulfillment order was created.
• fulfillBy: The date by which the fulfillment order should be fulfilled by the merchant.

As of today, the read_validations access scope will be required for the validation and validations queries. The write_validations access scope is required if you're using the validationCreate, validationUpdate or validationDelete mutations.

If you're building an extension for Cart and Checkout Validation configuration check our updated tutorial on Shopify.dev to see how to update it so that you don't need the new access scope.

As of 2024-04, fields that returned a count of resources will be removed and replaced with new count fields that have consistent API design and improved features.

API design and naming

Count fields are now standalone fields with a common naming pattern and their own arguments instead of being a field under a connection type.

Before:

query {
  products(first: 0) {
    totalCount
  }
}

After:

query {
  productsCount {
    count
  }
}

In the before example, the products connection field was overloaded with multiple behaviors (count and pagination) which caused confusion as to how, and if, arguments affected the resulting count.

With the new count fields, there's one clear behavior and it simplifies how field arguments affect the count.

Return type

Instead of varying Int or UnsignedInt64 return type, all count fields now return a Count object type with precision and count fields.

Precision

The new precision field indicates if a server limit was reached such that we returned early, reporting that there were "at least" n records.

For example, counting the number of products has a server limit of 10,000. If there were 42 products, the count object would look like { count: 42, precision: "EXACT" }. If there were 10,042 products, the count object would look like { count: 10000, precision: "AT_LEAST" }

Filtering

Some count fields will now accept filter arguments matching that of a neighboring connection, such as products and productsCount.

Migration

• CatalogConnection.totalCount --> CompanyLocation.catalogsCount, Market.catalogsCount, QueryRoot.catalogsCount
• Collection.availablePublicationCount --> Collection.availablePublicationsCount
• Collection.productsCount --> Collection.productsCount
• Collection.publicationCount --> Collection.resourcePublicationsCount
• Company.contactCount --> Company.contactsCount
• Company.locationCount --> Company.locationsCount
• Company.orderCount --> Company.ordersCount
• CompanyLocation.orderCount --> CompanyLocation.ordersCount
• CompanyLocationCatalog.companyLocationsCount --> CompanyLocationCatalog.companyLocationsCount
• CustomerJourneySummary.momentsCount --> CustomerJourneySummary.momentsCount
• DeliveryLocationGroup.locationsCount --> DeliveryLocationGroup.locationsCount
• DeliveryProfile.productVariantsCount --> DeliveryProfile.productVariantsCount
• DeliveryProfile.productVariantsCountV2 --> DeliveryProfile.productVariantsCount
• DiscountCodeApp.codeCount --> DiscountCodeApp.codesCount
• DiscountCodeBasic.codeCount --> DiscountCodeBasic.codesCount
• DiscountCodeBxgy.codeCount --> DiscountCodeBxgy.codesCount
• DiscountCodeFreeShipping.codeCount --> DiscountCodeFreeShipping.codesCount
• FulfillmentOrderLocationForMove.availableLineItemsCount --> FulfillmentOrderLocationForMove.availableLineItemsCount
• FulfillmentOrderLocationForMove.unavailableLineItemsCount --> FulfillmentOrderLocationForMove.unavailableLineItemsCount
• InventoryItem.locationsCount --> InventoryItem.locationsCount
• PriceRule.discountCodesCount --> PriceRule.discountCodesCount
• Product.availablePublicationCount --> Product.availablePublicationsCount
• Product.mediaCount --> Product.mediaCount
• Product.publicationCount --> Product.resourcePublicationsCount
• Product.sellingPlanGroupCount --> Product.sellingPlanGroupsCount
• Product.totalVariants --> Product.variantsCount
• ProductBundleComponent.componentVariantsCount --> ProductBundleComponent.componentVariantsCount
• ProductBundleComponent.nonComponentVariantsCount --> ProductBundleComponent.nonComponentVariantsCount
• ProductComponentType.componentVariantsCount --> ProductComponentType.componentVariantsCount
• ProductComponentType.nonComponentVariantsCount --> ProductComponentType.nonComponentVariantsCount
• ProductConnection.totalCount --> Channel.productsCount, Collection.productsCount, QueryRoot.productsCount
• ProductVariant.sellingPlanGroupCount --> ProductVariant.sellingPlanGroupsCount
• Publishable.availablePublicationCount --> Publishable.availablePublicationsCount
• Publishable.publicationCount --> Publishable.resourcePublicationsCount
• QueryRoot.channelCount --> QueryRoot.publicationsCount
• QueryRoot.companyCount --> QueryRoot.companiesCount
• QueryRoot.discountCodeCount --> QueryRoot.discountCodesCount
• QueryRoot.giftCardsCount --> QueryRoot.giftCardsCount
• QueryRoot.publicationCount --> QueryRoot.publicationsCount
• QueryRoot.segmentCount --> QueryRoot.segmentsCount
• SellingPlanGroup.productCount --> SellingPlanGroup.productsCount
• SellingPlanGroup.productVariantCount --> SellingPlanGroup.productVariantsCount
• Shop.limitedPendingOrderCount --> QueryRoot.pendingOrdersCount
• Shop.pendingOrdersCount --> QueryRoot.pendingOrdersCount
• SubscriptionBillingCycleEditedContract.lineCount --> SubscriptionBillingCycleEditedContract.linesCount
• SubscriptionContract.lineCount --> SubscriptionContract.linesCount
• SubscriptionContractBase.lineCount --> SubscriptionContractBase.linesCount

As of 2024-04, you now have read access to metafields on Company and CompanyLocation resources via the Customer Account API.

Learn more about the Metafield object on the GraphQL Customer Account API at Shopify.dev.

As of version 2024-04 of the Admin GraphQL API, you can use the productOptionsCreate, productCreate, and productOptionUpdate mutations to create metafield-linked product options.

Metafield-linked product options are only available in Shopify taxonomy early access.

Learn more about metafield-linked product options.

With the 2024-04 API release, along with the introduction of the new GraphQL product APIs, we are removing management of both the variants and options via the GraphQL ProductInput object and have marked as deprecated the /products and `/variants' REST API endpoints.

Below you can find migration information for public and custom apps built on existing GraphQL and REST product APIs.

Public Apps

All public apps built on existing GraphQL product APIs or REST product APIs must migrate to the new GraphQL product APIs by Feb 1st, 2025.

Custom Apps:

Custom apps built using the existing GraphQL product APIs must migrate to the new GraphQL product APIs by April 1st, 2025.

Custom apps built on REST will also need to migrate if they end up needing to support more than 100 variants.

Custom apps built on REST that do not need to support more than 100 variants can continue to use the deprecated REST product APIs, however it is important to note:

-Developers should expect that the GraphQL API will be the only supported API over the long term and will be made aware of these timelines as they become available.

-The deprecated REST product APIs are in maintenance mode; all new features and support will be built only for the new GraphQL product APIs.

-Any merchant using custom apps built with these deprecated APIs will not be able to increase their variant limit past 100.