Developer changelog

We've released a new commerce-oriented type system for metafields. Metafields that are created with these new types from our APIs are now more interoperable across our system.

You can use the type system through a new type field that replaces the existing valueType field, which is now deprecated. To make the migration easier, this is a non-breaking change. The deprecated valueType field will be removed in 2022-01.

To learn more about the API changes, refer to the API specific reference documentation:

• Admin REST API
• Admin GraphQL API
• Storefront API reference

If you’re a theme developers, then you can now use dynamic sources to insert standard metafields and known resource properties as setting defaults.

Learn more about the type system and how to migrate to it in the Metafields documentation.

Theme Check scans themes for errors and highlights Shopify theme and Liquid best practices. You can run these checks as a part of the Shopify Liquid Visual Studio Code extension. Theme Check identifies several types of issues within your theme code, including:

• Liquid syntax errors
• Missing templates
• Unused variables and snippets
• Unknown and deprecated tags
• Excessive snippet nesting
• Performance issues

Learn more about Theme Check.

Development themes are temporary, hidden themes that are connected to the Shopify store you’re using for development. When you run shopify theme serve, Shopify CLI automatically creates a development theme inside the store you’re working on, and will reuse that theme each time shopify theme serve is subsequently run during the same session. You don’t need to worry about others viewing or making edits to it because development themes are not visible on the Online store > Themes page.

Learn more about Development Themes.

Themes can now use JSON templates in place of Liquid templates for all template types except for gift_card and robots.txt.

Using the new JSON template files, you can define which sections should appear by default when your theme is first installed, and which order they appear in. Merchants can add, remove or reorder sections of JSON templates using the theme editor.

You can also connect theme settings to dynamic sources to pull dynamic information from the store. Dynamic sources can be metafield values or resource attributes.

Learn more about JSON templates and how to update your themes to use this new architecture.

To see a model of how you can implement JSON templates, take a look at the /templates directory of the Dawn GitHub repo.

We’ve also made other notable improvements to Liquid:

• Moved theme translations currently defined in the schema into locales/ files.
• Added Bundled Section Rendering in JavaScript endpoints to offload client-side rendering from themes.
• Updated specialized theme setting types to return Liquid objects instead of resource handles.
• Updated filters and attributes for functionality such as preloading critical CSS, adding html attributes to links, and removing items from carts.

We've released a new commerce-oriented type system for metafields. Metafields created with these new types from our APIs will be more interoperable across our system.

The type system is exposed through a new type field. The type field replaces the valueType field, which is now deprecated, and will be removed in our 2021-10 release.

Most new types map to the old MetafieldValueType enum, except for json_string and json. json replaces json_string, but json_string will continue to exist because it behaves differently than the new json type when referenced in Liquid.

Note: json_string will not automatically migrate to the json type.

Learn more about the type system and how to migrate to it in the Metafields documentation.

To learn more about these API changes, refer to our API reference documentation:

• Admin REST reference
• Admin GraphQL reference
• Storefront API reference

App developers can now integrate their apps into the Online store with theme app extensions. A theme app extension is a bundle of app block definitions and supporting files. App blocks can be added, removed, and configured directly from the theme editor without having to touch a theme’s code. This means uninstalls are also cleaner, with ghost code automatically removed.

Learn more about theme app extensions.

Dawn is Shopify’s first open source reference theme–built with performance and flexibility in mind, and using Online Store 2.0 features, including JSON templates, which support app blocks and sections on all pages.

Dawn uses a HTML-first, Javascript-only-as-needed approach to theme development, and can be used as a model for building new themes on Shopify. Using Shopify CLI, theme developers can clone Dawn as a starting point for building new themes.

View the Dawn repository on GitHub.

The Shopify Subscription APIs now support Authorize.net!

We have updated our CustomerPaymentMethod API on the September 2021 release to allow Shopify to store credit cards from Authorize.net and be used by the SubscriptionContract API.

Learn more about Shopify Subscription APIs.

Accurate and reliable sales data is critical to our merchants' businesses. It surfaces the insights they need to report on sales, reconcile their accounts, and measure and improve the performance of their business.

Shopify is releasing a new set of APIs that provide app developers the ability to query a list of all sales related changes on any Shopify order. You can now have a single consistent way to ensure your app is retrieving the most up to date and precise sales data as opposed to stitching order and sales data together through multiple resources. The APIs offer a variety of helpful metrics regarding each sale including detailed information about discounts, taxes, and the additional ability to reference information about the line item associated with the sale. You can think of it as a queryable audit trail to track all order changes from new sales, order edits, returns, and more.

To learn more about the new APIs, visit our getting started guide in the Shopify Developer Docs.

The Storefront API, which was previously limited to only private apps and public sales channel apps, can now also be used by custom apps to create custom buying experiences.

Learn more about the Storefront API here.

With the Developer Console, you no longer need to build your app extension in an isolated environment, you can now test your app extension with real store data in a local store environment. Any changes made to your local environment will render immediately, meaning you no longer need to publish your app to view your modifications.

You can also render both desktop and mobile testing environments.

Learn more about product subscription app extensions and the developer console.

App developers and their teams can independently investigate billing questions from merchants and issue app refunds directly from the Charge Overview page. Developers no longer need to contact Shopify Support to issue app refunds. By responding to merchant billing support inquiries directly, app developers can increase merchant satisfaction.

Staff acounts can use the new Manage refunds permission to issue app refunds so that app developers can decide which team members perform refunds. Developers can issue refunds for app charges up to $1,000.00 USD and app charges that were created less than a year ago.

To learn more about partner app refunds, refer to: Issuing app refunds page

The new Theme Kit Access app makes it easier for merchants to grant access to their theme. Instead of relying on a private app API password to authenticate, merchants can now leverage the Theme Kit Access app to create, share, and manage Theme Kit access with their partners.

To start leveraging the Theme Kit Access app, click here.

To reduce the complexity of searching for apps, we’ve reduced the number of app categories and subcategories in the Shopify App Store, and renamed some of our categories to better fit the merchant's vocabulary and search intent.

This change means that most developers will find their apps listed in different or renamed categories and subcategories, and therefore some might also have a different page rank.

To learn more about app store categorization, please visit the shopify.dev

You can now iterate through the global Liquid pages object, instead of only being able to directly reference known pages through their handle. This allows you to access a paginated pages listing of up to 50 items at a time and produce HTML that is conditional to the page data that is available.

You can return properties for a specific page using {{ pages.pagename.propertyname }}:

<h1>{{ pages.about.title }}</h1>
<p>{{ pages.about.author }} says...</p>
<div>{{ pages.about.content }}</div>

You can also interate through up to 50 pages at a time with pagination:

<ul>
{%- paginate pages by 50 \-%}
    {%- for p in pages -%}
        <li>{{p.title}}</li>
    {%- endfor -%}
    {{ paginate | default\_pagination: next: 'Older', previous: 'Newer' }} 
{%- endpaginate \-%}
</ul>

We have added a new payment method type, CustomerPaypalBillingAgreement, to the 2021-07 release candidate that allows the ability to store Paypal Billing Agreements in Shopify to be used by SubscriptionContracts.

This change also introduces two new mutations. One to create a PayPal billing agreement for a customer, and one to update existing agreements. For more information on the new mutations, visit our documentation on customerPaymentMethodPaypalBillingAgreementCreate and customerPaymentMethodPaypalBillingAgreementUpdate

We've released the localization form, which lets you build country selectors into themes. Merchants can now offer different prices for different countries that share the same currency with international pricing.

The currency form remains backwards compatible for new and existing themes, however using the localization form is highly recommended.

Learn more about the localization form.

As of May 2021, Shopify will automatically minify theme CSS when it is requested by the storefront. Minified CSS files are cached until the next time the underlying CSS file is updated.

Minification improves storefront performance, leading to a better buying experience for customers.

Learn more about performance and its benefits in the Shopify Help Center.

Apps can now query SellingPlanGroups that were created by another app using the new Shopify API Search query term app_id.

The app_id can be one of the following terms:

1. CURRENT (sellingPlanGroups(query:"app_id:CURRENT")) - The default behavior, where it returns all SellingPlanGroups created by the requesting app.
2. ALL (sellingPlanGroups(query:"app_id:ALL")) - Returns all SellingPlanGroups from all apps.
3. An app id number (sellingPlanGroups(query:"app_id:2525000000")) - Returns all SellingPlanGroups for the specified app id.

Learn more about the SellingPlanGroups query in the query root documentation.

Orders that include a post-purchase offer may now have fulfillment holds on inventory. These holds occur after payment is accepted, before the customer decides whether they will add items to their order. Like an edited order, the fulfillable_quantity of line items on post-purchase eligible orders are subject to change before fulfillment.

A few things to note about orders with post-purchase offers:

• When a customer places an order that qualifies for a post-purchase offer, any line items on an order will have a fulfillable_quantity of 0 while Shopify waits to see if there will be more items added to the order. The order fulfillment_status will be on_hold, and FulfillmentOrders in version ≥2021-07 will have a status of ON_HOLD. API versions before 2021-07 will return no FulfillmentOrders.
• When a customer accepts a post-purchase offer or does not return to the post-purchase page for 60 minutes, the fulfillable_quantity will update to reflect the number of items that should be shipped. It is also possible that additional line items will appear on the order at this time. The order fulfillment_status will change to null. The FulfillmentOrder status will change to OPEN, and clients calling versions before 2021-07 will now be able to see FulfillmentOrders associated with the order.

The most reliable source of timely fulfillment data is the FulfillmentOrders endpoint, available in both REST and GraphQL. Clients calling the most recent version of FulfillmentOrders will always include all relevant, up-to-date information about fulfillments.

FulfillmentOrder GraphQL Reference FulfillmentOrder REST Reference

For more information on using Fulfillment Orders, visit our guide on managing fulfillment with Fulfillment and FulfillmentOrder resources.

To be notified when the post-purchase checkout extension becomes widely available for new apps, subscribe to the developer changelog for updates.

The discount code creation job has been updated to enhance its performance, including an update to our request throttling. For best results, enqueue a discount code creation job, and then enqueue another job when the job completes.

For more information about discount code creation job, visit our developer documentation.

We've added an activity log for app store ads to help advertisers keep track of who completed which actions, and at what time, within their ads account.

To access the activity log, go to your Ads page and then click Activity log.

The following actions are tracked as of April 14. Some events may appear as early as March 31.

• Ad creation
• Ad status changes (active / paused / archived)
• Ad budget changes
• Keyword creation (inclusive of negative keywords)
• Keyword status changes (active / paused / removed)
• Keyword bid changes.

Learn more about advertising in the Shopify App Store on Shopify.dev.

Zone information for United Kingdom will now return the following possible constituent countries for the UK:

• Name: England, Code: ENG
• Name: Northern Ireland, Code: NIR
• Name: Scotland, Code: SCT
• Name: Wales, Code: WLS
• Name: British Forces, Code: BFP

Merchants use provinces in their shipping zones settings to specify the rates for a country or province.

All existing shops that have United Kingdom in a zone will automatically include all UK constituent countries.

This data can be queried from the GraphQL admin api or REST admin api

Shipping/billing addresses in the UK are not supposed to contain these consitituent countries. To ensure that the shipping/billing address is displayed correctly, ensure you are using the format_address liquid filter to format correctly based on the address locale.

We've introduced a host query parameter as part of the URI that Shopify redirects to after the OAuth grant flow. This parameter represents the domain that hosts your embedded app and is needed to initalize App Bridge 2.0 in the Shopify admin.

For most apps, there is no action required following this change. This change might be a breaking change if your app's hmac verification step doesn't verify the hmac using all the parameters available in the redirect URI.

For steps to verify the hmac parameter, see the "Verification" step of the Authenticate with OAuth guide.

To see what other changes are needed to use App Bridge 2.0, see Migrate your app to App Bridge 2

Store access controls adds enhanced workflows that let you work more securely on development stores, managed stores, and Plus Sandbox stores with your team and contractors.

Owners and staff members with the Manage members permission can now:

• Specify a level of access, for each type of store, for a staff member. You can select between no access, access to all stores, or access to specific stores. A staff member can log in to a store only when they’ve been allowed access.
• Allow select staff members to add, archive, or transfer ownership of stores.
• Provide access to a specific store for a staff member from the Team or Stores section of the Partner Dashboard.

To get started, head over to the Team section of the Partner Dashboard, and open up any team member’s profile. Learn more about the features in our Help documentation.

To help maintain app quality and marketplace trust on the Shopify App Store, we’re increasing app quality checks to ensure that published apps:

• Meet the most up-to-date version of requirements for public apps
• Meet our new app performance requirement to ensure apps don’t negatively impact store speeds
• Have clear and trustworthy app listings, that are without incentivized reviews.

If something is found during the quality check of your listed app that does not meet our criteria, then the app store team will email you with the required changes and next steps.

The Embedded App SDK (EASDK) and backwards compatibility layer are being removed from Shopify on January 1, 2022.

All embedded apps using EASDK or the backward compatibility layer are requested to move to App Bridge 2.0 as soon as possible in order to provide a more consistent and performant app loading experience for merchants.

Additionally, starting May 1, new embedded public apps submitted for review to the Shopify App Store will be required to be on App Bridge 2.0 with session tokens implemented.

To learn how to update your apps, refer to the migration guide on Shopify.dev.

This is a possibly breaking call, where there's no way for Shopify to know if your app is using the 'one' value. As a result, we will not delist any app that continues to get this warning.

As of API version 2020-07, we're updating the allocation method for discounts that have set the target_selection as explicit. Currently, Shopify applies these discounts to a single line item, which corresponds to an allocation method of one. With this change, the allocation methods will instead include "each" and "across".

We're making this change to add "each" functionality, and simplify the discount syntax, as "one" and "across" functionally both discount the final price by a set amount.

This change also affects discount_applications on the following webhook payloads :

• orders/cancelled
• orders/create
• orders/fulfilled
• orders/paid
• orders/partially_fulfilled
• orders/updated

For more information, please visit the community forum post.

We’ve just released a change to predictive search that fixes the issue where predictive search API returns results in multiple languages. This helps customers searching for products on translated storefronts.

Recent changes requiring two-factor authentication on payments in Europe have required 3D Secure 2.0 (3DS) coverage for subscriptions particularly in a recurring billing scenario.

This update includes the full buyer end-to-end experience for a 3DS challenge when attempting recurring billing.

If a European buyer’s bank requires authentication, then Shopify notifies the buyer in an email of the 3DS challenge requirement. If the buyer authentication fails, then it's the partner’s responsibility to retry the payment.

For information on 3DS support for subscriptions and more detail on Shopify and partner responsibilities in this process, click here.

Introducing price lists, a new API resource that allows you to configure international pricing.

Price lists can be used to create percentage price adjustments and fixed variant prices that are applied in the online store and checkout.

Learn more about the price list API in Shopify Developers.

We’ve introduced a new app charge overview page in the Partner Dashboard, so app developers can view all one-time charges, app subscriptions, and usage charges made to merchants. This helps developers access key details to investigate app charges for answering merchants’ billing inquiries and better understand payouts.

Learn more about the app charge overview page on Shopify.dev

As of API version 2021-04, GiftCard GraphQL APIs are available for custom and private apps installed on Shopify Plus stores. App developers can now use the APIs to query all gift cards within a shop, as well as create, update, and disable gift cards. To get started, check out our tutorial on managing gift cards using the GraphQL Admin API.

GiftCard REST API availability has also been extended to custom apps installed on Shopify Plus stores. Partners developing custom apps can now use Gift Card functionality when creating custom apps for Plus merchants. Learn more about the GiftCard REST resource in our developer documentation.

As of GraphQL API version 2019-04, the list of valid country codes will retroactively include TA (Tristan da Cunha) and AC (Ascension Island). These British Overseas Territories were formerly included under the GB country code, but they are now distinct in order to comply with post-Brexit mailing address formats. Our APIs already support other British Territories, including AI, BM, FK, GG, GI, GS, IM, IO, JE, MS, PN, SH, TC, and VG. This change affects the shipping locations for all merchants who ship to the “rest of world” shipping zone.

The impacted enums are CountryCode in the GraphQL Storefront API and CountryCode in the GraphQL Admin API.

This change will go live on March 22, 2021.

Over the next week, we’ll be rolling-out new metrics in the ads reporting dashboard for Shopify App Store ads. The new metrics will help developers to measure their return on ad spend, the number of customers gained through ads, and customer acquisition costs.

New metrics include: * Customers * Revenue * Customer Acquisition Cost * Return on Ad Spend * Conversion Rate

The new metrics will be available on impressions served on or after May 5, 2020.

These additional metrics and soon-to-be added personalized keyword optimization suggestions will help make sure that your advertising efforts trend towards a positive return on investment.

You can learn more about these new metrics on Shopify.dev and in frequently asked questions.

As of 2021-04, you can use the SUBSCRIPTION_POLICY value in the existing ShopPolicyType enum. This lets you retrieve and modify a shop's subscription policy.

Lean more about the ShopPolicy object and the shopPolicyUpdate mutation.

As of API version 2021-04, a new field called delivery_method is present on the FulfillmentOrder object in the REST Admin. This field can contain an id and a method_type. The method_type can be one of the following values: local, none, pick_up, retail, or shipping.

delivery_method represents the type of method that is used to transfer a product or service to a customer. The field was previously released in GraphQL API 2020-10 version.

For more information about FulfillmentOrder, visit our developer documentation.

Shopify now supports adding embedded Vimeo videos to products, leveraging the ExternalVideo object.

Many ExternalVideo API implementations assume that all external video objects represent YouTube videos. To help determine where the video is hosted, we're introducing the new field host to ExternalVideo that will return a MediaHost enum value (currently VIMEO or YOUTUBE).

Additionally, we're introducing two new MediaErrorvalues EXTERNAL_VIDEO_EMBED_NOT_FOUND_OR_TRANSCODING and EXTERNAL_VIDEO_EMBED_DISABLED for Vimeo error handling.

With the launch of automatic international tax-inclusive pricing, whether or not prices have taxes included can vary based on the customer's country.

This change introduces a new liquid method on the cart drop, cart.taxes_included.

Learn more about automatic international tax-inclusive pricing in the Shopify Developer Docs.

Products that require a subscription for purchase, but have no selling plans associated with the product variants, are no longer available for purchase in the Online Store sales channel. Previously, a product would become available as a one-time purchase if no selling plans were attached.

The Liquid property requires_selling_plan on Product and ProductVariants has been updated to reflect this change. The Liquid property still states whether a selling plan is required to purchase the product variant. Previously, the property would return false if the product was set as subscription-only in the admin, but had no selling plans associated with the product variants.

Learn more about setting products as subscription only.

If a merchant has used price adjustments by region, or set specific pricing by region, then those prices are now reflected in the presentment_prices property of Shopify's Product API. Prices for the Eurozone are still reflected as one price across all countries or regions that use the Euro.

Learn more about international pricing in the Shopify Help Centre.

Session token-based authentication is now required for all embedded apps submitted for app reviews. This update helps mitigate the risk of embedded apps failing due to third-party cookie browser restrictions. With session token-based authentication, embedded apps no longer rely on cookies to verify identity.

Learn more about how to authenticate your app using session tokens on Shopify.dev.

Kit, a Shopify app that automates some marketing tasks, and the Kit Skills API will be deprecated on April 1, 2021. The API will be removed on August 31, 2021, and won't work after that date.

To Kit Skills developers, we are grateful for your partnership and the amazing things that you do for Shopify merchants.

For more information, refer to the frequently asked questions in the Shopify developer documentation for Kit.

The DiscountCode lookup API now includes requested the API version in the location URL that it returns, instead of falling back to the earliest supported version.

Example: /admin/api/<API_VERSION>/price_rules/<PRICE_RULE_ID>/discount_codes/<DISCOUNT_ID>.json

Learn more about the DiscountCode lookup API on Shopify.dev.

We’ve released a new Shopify Admin API library for Node. This library makes interacting with the Admin API easier, to help accelerate app development for developers who use Node frameworks.

The following resources have been updated to use this new library:

• The koa-shopify-auth package
• Our Node + React app tutorial
• The Shopify App CLI

For more information on how to use this new library, refer to our Getting started guide. You can also submit issues and feature requests to the shopify-node-api repo.

The Shopify Subscription APIs now support Shopify Scripts.

For information on how to use Shopify Scripts with subscriptions, refer to Scripts for subscriptions in the Shopify Help Center.

For more information on the Subscription APIs and upcoming roadmap, including the timeline for upcoming features, visit the Subscriptions FAQ on Shopify.dev.

Shopify now supports adding embedded Vimeo videos to products, leveraging the external_video object.

Many ExternalVideo API implementations assume that all external video objects represent YouTube videos. To avoid any complications arising from this change, version 2021-01 and earlier of our APIs don't return ExternalVideo objects that represent Vimeo videos.

You can access Vimeo videos using the unstable version of our APIs. We will also be introducing the ability to detect the video host in 2021-04.

Learn more about Liquid media filters and the external_video object on Shopify.dev.

Over the next few weeks, we're rolling out a new webhook metrics report in the Partner Dashboard. This report lets you track failed webhook deliveries, monitor response times, and find removed webhook subscriptions for your public and custom apps in real time.

You can access the report from the Apps page of your Partner Dashboard. Click on the percentage in the Webhook deliveries column to view the webhook metrics report for your app.

You can search your detailed delivery logs by subscription ID, webhook ID, or shop ID to troubleshoot any failures, and keep your app reliably consuming webhooks and providing merchants with a great app experience.

Learn more about using the webhook metrics report on Shopify.dev.

You can now detect the theme editor programmatically using Liquid and JavaScript. In Liquid, you can use request.design_mode. In JavaScript, you can use Shopify.designMode.

Workaround methods, such as content_for_header contains in Liquid, or searching the page URL in JavaScript, aren't supported and won't continue to work in the new theme editor. To make your app or theme compatible with the new theme editor, you need to update your code to use a supported method.

Learn more about detecting the theme editor on Shopify.dev.

In our 2020-04 API version, we added validation requiring the compare_at_price field to always be greater than the price field on variants.

After further review of use cases around the current use of the compare_at_price field, we're reverting the addition of validation between the price and compare_at_price fields on variants, and notifications about this change as we will be removed from all versions.

If you're currently seeing notifications about this change in your API Health dashboard, you can safely ignore them. If you've already updated your app to handle this breaking change, there's no need for action. Your app will continue to function throughout the revert.