Developer changelog

Two new paremeters have been added to the full-funnel app install event for the Shopify App Store - shop_name and shop_url. These enhancements provide more insights on which merchant is installing an app.

Learn more about the new parameters and full-funnel attribution in the Shopify App Store docs.

On the app listing pages, Google e-commerce events have also been implemented to enhance tracking capabilities. The events view_item and addtocart will now be sent to Google Analytics, allowing for more precise data analysis.

For further details, check out the section on Google e-commerce events in the Shopify App Store docs.

The quantityAvailable and availableForSale fields will now reflect country-specific inventory availability, scoped to the specified market country of the Product Feed. The Fulfillable Inventory feature must be enabled on the shop.

Learn more about Fulfillable Inventory on the Shopify help docs.

The number of post-purchase upsell offers that customers can accept has been increased from two to three. With this change, merchants can increase their order value even more through post-purchase upsell offers.

We highly recommend that you review any custom code that pertains to post-purchase offers to ensure an optimal buyer experience.

Learn more about post purchase offers on shopify.dev

As of the GraphQL Admin API version 2024-10, we're improving the GiftCard endpoints and introducing GiftCardTransaction types. The gift card endpoints are now open to all apps and shops, with no additional approval scopes or flags required.

We have added the following mutations:

• giftCardDeactivate renamed from giftCardDisable (deprecated).
• giftCardCredit to apply credit to a gift card returning a GiftCardCreditTransaction.
• giftCardDebit to apply debit to a gift card returning a GiftCardDebitTransaction.
• giftCardSendNotificationToCustomer to send the notification to the customer.
• giftCardSendNotificationToRecipient to send the notification to the recipient.

We have updated the following mutations:

• giftCardCreate to add recipientAttributes.
• giftCardUpdate to add recipientAttributes.

We have added and modified fields in the GiftCard object:

• Added updatedAt.
• Added recipientAttributes.
• Added transactions returning all transactions created by credits and debits.
• Renamed disabledAt to deactivatedAt (deprecated).

Developer action required

Developers using the existing giftCardDisable mutation will need to replace it with giftCardDeactivate

Developers using the disableAt property on the GiftCard object will need to replace it with deactivatedAt

To learn more about gift cards, refer to the gift cards documentation. To learn more about gift card recipient functionality, refer to the help center documentation for recipient fields

As of the Admin API version 2024-10, the fulfillmentOrdersReleaseHolds mutation has been deprecated.

Apps using this mutation should migrate to using the fulfillmentOrderReleaseHold mutation instead.

As of Admin GraphQL API version 2024-10, you can access QueryRoot.urlRedirectsCount field to retrieve the count of redirects.

Learn more about urlRedirectsCount on Shopify.dev.

As of the 2024-10 version of the GraphQL Admin API, the products query filter has been expanded to allow filtering on additional attributes: publication_ids, variant_id and variant_title.

Check out all products query attributes at shopify.dev for more details.

The following fields have been deprecated from the Abandoned Checkout REST API: cart_token, closed_at, currency, gateway, landing_site, fulfillment_service, grams, presentment_currency, referring_site, shipping_lines, token and total_weight fields

As of 2024-10, the endpoint is available via the newly published GraphQL abandoned checkout API.

As of the GraphQL Admin API version 2024-10, a id field is being added to the FulfillmentHold GraphQL object.

As of the GraphQL Admin API version 2024-10, an optional holdIds argument is being added to the fulfillmentOrderReleaseHold mutation. This will give apps the ability to release a hold by ID, ensuring that only the intended hold is released. It is highly recommended that apps supply the ids of any holds when releasing them. Releasing all holds on a fulfillment order will result in the fulfillment order being released prematurely and items being incorrectly fulfilled.

As of Admin GraphQL API version 2024-10, you can access Order.statusPageUrl field to retrieve the URL where the customer can check the order's current status.

Learn more about Order on Shopify.dev.

As of today, the Mobile performance: Uses App Bridge optimized loading on mobile devices standard that exists as part of admin performance is no longer required to apply for and maintain Built for Shopify status.

All apps now have this enabled by default.

As of September 12, 2024, the CustomerConsentCollectedFrom field will return SHOPIFY whenever SMS consent is captured in Shopify Checkout. Previously, it would return OTHER if the buyer consented to SMS marketing in checkout, but the sales channel of the checkout was not one owned by Shopify (Example, online store checkouts would return SHOPIFY while custom storefronts would return OTHER).

This applies to both the 1st party SMS consent UI, as well as any checkout UI extensions using the ConsentCheckbox or ConsentPhoneField UI components.

Other SMS consent capture flows are unaffected.

Hydrogen v2024.7.5 is out today. The September 2024 Hydrogen release contains several optimizations and bug fixes, including:

• Improved sitemaps (unstable) (#2478)
• Skeleton template search enhancements (#2363)
• Cart gift card support (#2298)
• Consent localization (#2457)
• Improved content security policy implementation (#2500)
• Infinite redirect fix for with URLs with // (#2449)
• Improved useOptimisticCart to optimistically calculate totals (#2459)
• Skeleton template mobile device link fix (#2450)
• Utilities privacyBanner and customerPrivacy have been added to useAnalytics and useCustomerPrivacy (#2457)

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

As of API version 2024-10, we're adding the new PRODUCTCATEGORYID as a column for the CollectionRuleColumn which is used to create automated collections. This field maps directly to the newly added Product Category as defined in the updated standard product taxonomy and will allow for the creation of smart collections based on this new category tree.

What's new?

• Introduction of PRODUCT_CATEGORY_ID Column: We are introducing a new column, PRODUCT_CATEGORY_ID, in the CollectionRuleColumn. This column will directly map to the category ID of a product, allowing for more precise and efficient collection rule creation based on product categories as defined in the updated standard product taxonomy.

What's deprecated?

• Deprecation of PRODUCT_TAXONOMY_NODE_ID Column: The PRODUCT_TAXONOMY_NODE_ID column is being deprecated. This column previously used the now-deprecated productCategory field on products, the previous method for categorising products before the updated standard product taxonomy was introduced this year. Developers should transition to using the new PRODUCT_CATEGORY_ID column to ensure newly created products that necessarily use the updated product taxonomy are included in automated collections as expected.

Developer action required

Developers are encouraged to update their implementations to use the new PRODUCT_CATEGORY_ID column when specifying product attributes for populating smart collections. The deprecated PRODUCT_TAXONOMY_NODE_ID will remain functional but is scheduled for removal in a future API version. Transitioning early will ensure smoother operations and access to the enhanced functionality provided by the new schema.

Example of updated usage

To create a smart collection using the new PRODUCT_CATEGORY_ID, modify the collection creation mutation as follows:

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      descriptionHtml
      handle
      sortOrder
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
        }
      }
    }
  }
}
{
  "input": {
    "title": "Our entire shoe collection",
    "descriptionHtml": "View <b>every</b> shoe available in our store.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": {
        "column": "PRODUCT_CATEGORY_ID",
        "relation": "EQUALS",
        "condition": "gid://shopify/TaxonomyCategory/aa-5" 
      }
    }
  }
}

Learn more about collection creation at [Shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate)

Webhooks will now be retried a total of 8 times over 4 hours using an exponential backoff schedule. This should allow sufficient time for transient errors to be resolved.

When webhooks are retried, they will be delivered with the original payload from the time they were triggered. Partners should utilize the X-Shopify-Triggered-At timestamp in the header, or a timestamp from the payload to determine if the payload is stale.

Retried webhooks will be delivered to the subscription's address that was configured when the webhook was triggered. Updating the subscription's address during a retry cycle will not result in the webhook being delivered to the new address. When migrating webhooks to a new endpoint, it is recommended to keep both endpoints active for a short period of time to ensure a smooth transition.

These changes aim to improve the consistency, efficiency and reliability of webhook delivery while minimizing the impact on partners.

Static app navigation for admin apps is no longer supported. Creation and editing of static navigation are no longer available on the the Partners dashboard. You can delete existing menus using the Partners dashboard until December 2024. After December 2026, static navigation items will be automatically removed from apps.

To configure app navigation, use the App Bridge navigation menu web component or React component to add navigation to your app and delete the existing navigation items from the Partners dashboard.

As of 2024-10, we're deprecating fulfillmentCreateV2 and fulfillmentTrackingInfoUpdateV2. Instead, please use fulfillmentCreate and fulfillmentTrackingInfoUpdate.

Note that the behavior of the new mutations remains the same as the previous ones; the only change is the removal of V2 to ensure consistent naming across all mutations.

As of the 2024-10 release of the Admin REST API, the location resource will be gated by the locations scope.

Attempting to access the location resource without the read_locations scope will return a 403 Forbidden error. If your app gets the location resource, then you will need to request the correct read_locations scope before migrating to the 2024-10 API version.

To help merchants discover the freshest and most well-integrated themes for their store, we've shipped an update to the Theme Store homepage to highlight Top and New themes (published in the last 60 days).

As of GraphQL Storefront API 2024-10, you can now retrieve product taxonomy categories in storefronts. This information is also available through the Liquid API.

This will allow you to customize the buyer experience in storefronts based on product taxonomy. Learn more about product taxonomy in our help docs.

See Shopify.dev for documentation on the new Liquid object and the upcoming GraphQL type.

As of Graphql Admin Api version 2024-10, calls to mutation inventoryActivate can use an optional parameter stockAtLegacyLocation. Setting this parameter to true will allow inventory to be activated if the locationId provided is associated with a fulfillment service that does not permit sku sharing.

If an item is activated at a location that does not permit sku sharing then the item will be deactivated at all other locations.

If an item is currently active at a location that does not permit sku sharing and you want to activate that item at another location the stockAtLegacyLocation parameter also needs to be set to true.

Learn more about inventoryActivate on Shopify.dev

As of 2024-10, ReverseFulfillmentOrderLineItem.fulfillmentLineItem field is nullable. A ReverseFulfillmentOrderLineItem will not always be associated with a FulfillmentLineItem anymore. The non-null fulfillmentLineItem field on the older API versions will return a graphql error when the fulfillment line item does not exisit.

Learn more about ReverseFulfillmentOrderLineItem on Shopify.dev.

As of Admin GraphQL API version 2024-10, use Order.lineItems instead of lineItemsMutable field to get a list of the order's line items.

Learn more about Order on Shopify.dev.

We are retroactively adding Customer, Order, Company, and Model3d graphql types to the MetafieldReference union for Admin API from 2024-01 and onward.

Additionally, TaxonomyValue will be added in 2024-04 to align with the version the type was introduced.

We are requiring apps to meet at least Level 1 Protected Customer Data Requirements in order to access the Customer Account GraphQL API. This change is applicable to all API versions. We recognize that this may be a breaking change for public apps that use the Customer Account API and is necessary to ensure the protection of customer data.

This change will not impact Hydrogen and Headless storefronts or Custom Apps since they already have access to Level 1 and Level 2 Protected Customer data.

Partners that are part of the Customer Account UI Extensibility developer preview and are calling the Customer Account API from their extensions will need to request access to continue to access the API.

Learn more about Protected Customer Data on shopify.dev.

As of 2024-10 version, we are adding productVariantsCount field to the Admin GraphQL API.

Learn more about productVariantsCount on Shopify.dev.

The following changes have been made:

• Technical criteria checklist has been renamed to Technical criteria
• App distribution page layout has been updated, and the content for some standards have been re-worded for clarity.
  • Added: A new section Category-specific criteria to outline criteria for specific app features.
  • Renamed: Build for performance is now Performance.
  • Renamed: Usefulness criteria is now Merchant utility
  • Combined: Protect app safety, security, and reliability and Design for ease of use are now Design and functionality
  • Removed: Share app info and benefits along with the standard Make sure your app listing content is up-to-date. This standard was intended to encourage completion of new app listing form fields introduced in the past, which all partners now have completed.

• Merchants can now filter themes by 3 new features: "Quick Order List", "Sign in with Shop" & "Swatch Filters". And we have removed 3 feature filters: "Product reviews", "Event Calendar" & "Store Locator".
• Each Theme's listing page has been updated to include quality signals and new styling.
• The order of Theme cards on your Partner-specific "All Theme Page" has changed to be "Newest to Oldest".

As of the 2024-10 release of the GraphQL Admin API, we're removing the error codes: HAS_OPEN_TRANSFERS_ERROR and FAILED_TO_RELOCATE_OPEN_TRANSFERS from LocationDeactivateUserErrorCode.

The error codes were not being returned from the LocationDeactivate mutation, as such, they will no longer be listed as possible error codes.

If you are explicitly checking either of these error codes, you should remove references to them.

As of GraphQL Admin API version 2024-10, we're cleaning up the shopifyPaymentsAccount endpoint and removing several unused fields.

As of Shopify CLI 3.66, log streaming and replay for Shopify Functions is generally available.

Log streaming for Shopify Functions enables faster development, testing, and debugging of functions by bringing function execution logs to Shopify CLI. You can also replay function executions locally using input from these logs.

Learn more about Shopify Functions log streaming on Shopify.dev.

As of GraphQL API version 2024-10, we are expanding media capabilities in the productSet mutation:

• We are adding a new field type FileSetInput, which is a derivative of the FileCreateInput, with an added id field, which results in being able to both work with already existing media and create new files while using the same type.

• ProductSet.mediaIds field is being removed and replaced with the new **files** field, which expands the former's functionality by allowing you to also create new files to be associated with the product specified. This field utilizes the new FileSetInput type.

• ProductSetVariantInput.mediaId is being removed and replaced with **file** field, which will associate the file with the variant. This field utilizes the new FileSetInput type.

For more detailed information and examples, visit our productSet documentation on Shopify.dev.

When accessing metafield namespaces or metaobject types, you no longer need to hard code app--{app_id}. The $app reserved prefix is now available to use in your Liquid files.

Learn more about using reserved prefixes in theme app extensions on Shopify.dev developer docs.

We have improved the design and function of Dynamic Checkout and Accelerated Checkout buttons on storefront pages. These updates ensure that the buttons now support features like Shopify Functions and Product Bundles, providing better performance and a smoother user experience. These changes are now live on development stores and will begin rolling out to all merchants September 15.

Please note that the Accelerated Checkout buttons now hide their HTML in a custom element with a closed shadow DOM. This means that any styling or event tracking that targets the existing HTML structure of these buttons will break.

Please review this guide and the Accelerated checkout button reference to ensure your customizations remain compatible with the latest updates.

We are modifying how cart queries and mutations behave when the Storefront API Cart ID is missing the key param. This behavior is applied retroactively to all versions of the Storefront API.

An example cart ID: gid://shopify/Cart/c1-7a2abe82733a34e84aa472d57fb5c3c1?key=824bdj25mhg1242bdb385

• Queries: Querying a cart without including the key param will result in a cart with the buyer's private details removed.

• Mutations Updating a cart without including the key param will result in an error : The specified cart does not exist.

We are deprecating productChangeStatus mutation. Use productUpdate mutation instead.

You will need to migrate to the new endpoint by January 2025 when we will remove access to the productChangeStatus mutation.

Learn more about product mutations at shopify.dev

Theme cards on the Theme Store have been updated. Theme cards are now:

1. Visually simpler (feature tags have been removed)
2. Have a link to the listing for the Theme title
3. Have a badge to identify Themes that are new to the Theme Store
4. Show a Themes percentage positive reviews, and the number of reviews it's received

No action is needed from Theme developers.

We are extending the promotion period for new Themes. Now, new Themes will be highlighted for a longer period than before.

We've added support for the Link metafield type to the metafield_tag filter in Liquid.

Furthermore, you can now consume Link metafields using dynamic sources in inline_richtext and richtext theme settings. Link metafields will be inserted with the metafield_tag filter by default for these setting types.

Learn more about metafield filters in Shopify.dev

We've added error messages to the Shopify Pixel Helper so that you can more easily debug your custom pixels. The Pixel Helper will display uncaught errors that occur at the top level or in the callback function. Top level errors will be viewable when the Pixel Helper loads. Callback error messages will be viewable when an event with a red dot is expanded.

As of the GraphQL Admin API version 2024-10, we're removing a number of MetafieldStorefrontVisibility-related fields, queries, and mutations.

Use the more flexible MetafieldDefinition.access field instead.

• We're removing MetafieldDefinition.visibleToStorefrontApi.
  • Use MetafieldDefinition.access instead.
• We're removing MetafieldDefinitionInput.visibleToStorefrontApi.
  • Use MetafieldDefinitionInput.access instead.
• We're removing MetafieldDefinitionUpdateInput.visibleToStorefrontApi.
  • Use MetafieldDefinitionUpdateInput.access instead.
• We're removing metafieldStorefrontVisibilityCreate
  • Use MetafieldDefinitionUpdate instead.
• We're removing metafieldStorefrontVisibilityDelete
  • Use MetafieldDefinitionUpdate instead.
• We're removing metafieldStorefrontVisibilities
  • Use MetafieldDefinition.access instead.
• We're removing metafieldStorefrontVisibility
  • Use MetafieldDefinition.access instead.

Learn more about MetafieldDefinition.access at https://shopify.dev/docs/api/admin-graphql/2024-07/objects/MetafieldAccess

Address autocomplete apps can now set latitude, longitude and company name when an address suggestion is selected during checkout. If provided, the coordinates of a delivery address are sent to the Carrier Service API when calculating shipping rates. The company name field can be populated in checkout if the field is enabled for the merchant’s store.

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

Hydrogen v2024.7.3 is out today. The August 2024 Hydrogen release contains several quality-of-life improvements, optimizations and bug fixes:

• Custom .env file support (#2392)
• Improved performance of currency formatting (#2372)
• Improved handling of remix.config.js / vite.config.js files (#2379)
• Simplified context creation with a new createHydrogenContext function (#2333)
• Script component now takes a waitForHydration prop (#2389)
• Google web cache fix (#2334)
• Custom logger support for vite.config.js. (#2341)
• Subrequest profiler virtual root fix (#2344)
• CLI: Auth flow fix. (#2331) \

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

As of the GraphQL Admin API version 2024-10, an access argument is being added to the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable GraphQL mutations.

As of the GraphQL Admin API version 2024-10, we're deprecating the visibleToStorefrontApi argument on the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable GraphQL mutations. Use the new access argument instead.

The new access argument allows developers to specify more granular access controls when enabling a standard metafield definition template.

Learn more about standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable at https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/standardMetafieldDefinitionEnable and https://shopify.dev/docs/api/admin-graphql/unstable/mutations/standardMetafieldDefinitionsEnable.

*Updates to our Partner Program Agreement and API License and Terms of Use *

EFFECTIVE AUGUST 9, 2024 ACTION REQUIRED

We've made changes to our Partner Program Agreement and API License and Terms of Use. These updates include terms that are intended to support the growth of Shopify Partners and Merchants, while maintaining the security and integrity of products and services offered on our platform.

These changes come into effect as of today, August 9, 2024.

We encourage all developers on our platform to review and be familiar with the API License and Terms and the Partner Program Agreement, so that you understand how to build, run, and grow your app and development business on our platform.

For more information and frequently asked questions, please visit the Shopify Help Center.

As of the Admin API version 2024-10, apps will not be able to release fulfillment holds unless they have write access to it.

If your app has the write_merchant_managed_fulfillment_orders scope, you will be able to release holds on fulfillment orders assigned to a merchant managed location.

If your app has the write_third_party_fulfillment_orders scope, you will be able to release holds on fulfillment orders assigned to a third party location.

If your app has the write_marketplace_fulfillment_orders scope, you will be able to release holds on fulfillment orders which belong to one of your marketplace's orders.

How will this change effect my app?

This change will only effect apps which release fulfillment holds using the Admin API.

If your app does not currently have sufficient access scopes as defined above then you will need to request the correct access scopes before migrating to the 2024-10 API version.

When using the GraphQL API, if your app does not have sufficient access to release a hold, a user error with the code INVALID_ACCESS will be returned and the hold will not be released.

When using the REST API, if your app does not have sufficient access to release a hold, a 422 error code will be returned and the hold will not be released.

See the fulfillmentOrderReleaseHold mutation for more information on what scopes are required.

See the API access scopes section of the FulfillmentOrder resource for more information about these scopes.

You can now specify the category-related features your app offers. These structured app category details will appear on your App Store listing page and in the app comparison feature.

Fill out the app category details fields on your app listing pages so that merchants can more easily find and assess whether your app meets their needs.

For more information, please refer to our dev documentation.

As of 2024-10 version, the product create and update webhook payload contains information about the product category on a product.

The category field exposes a trimmed version of fields that are available on the Product GraphQL response.

To receive category in the webhook payload, specify version 2024-10 or newer as the webhook API version in your App Partner Dashboard.

Effective from July 29, 2024, a 30-day hold will be applied to your first payout. This change will only impact new partners who have not yet received their first payout. Learn more about payout schedules.

You can now specify the category-related features your app offers for 30 additional categories. Fill out the fields on your app listing pages so that merchants can more easily find and assess whether your app meets their needs. These structured app category details will appear on your App Store listing page and in the app comparison feature.

• Countdown timer
• Metafields
• Forms
• Navigation and menus
• Wishlists
• ERP
• Accounting
• Taxes
• Legal
• Wholesale
• Returns and exchanges
• Geolocation
• Stock alerts
• Pre-orders
• Web push
• Gift cards
• Donations
• Gift wrap and messages
• Giveaways and contests
• Surveys
• Image gallery
• Third-party logistics (3PL)
• Fraud
• Helpdesk
• FAQ
• Delivery and pickup
• Video and livestream
• Event booking
• Accounts and login
• Cash on delivery (COD)

For the other categories that already supports app feature details, see here and here. We plan to support all categories by August 2024.

For more information, please refer to our dev documentation.