Developer changelog

The length of newly generated Shopify access tokens will increase from 32 to 38 characters, adding a static prefix of shpat_ (for public apps), shpca_ (for custom apps), or shppa_ (for legacy private apps). This change will take effect on April 1st, and will impact all access tokens generated after this date.

This is a breaking change only if your application makes assumptions regarding the length of Shopify access tokens. For example, if your app store Shopify access tokens in a 32-character database field or validates that they are exactly 32 characters, then you should adjust your application or database so it can accept longer access tokens prior to April 1st. Existing access tokens will continue to function in their 32-character form until they expire or are re-requested.

Learn more about authenticating your Shopify app from the Shopify Help Center.

Today we are releasing a new developer preview to allow merchants the ability to charge duties calculated by Shopify during checkout and avoid surprise charges for their customers upon delivery.

As of the 2020-04 release, duties and taxes charged on international orders through checkout can be viewed through the REST and GraphQL API, and refunded through the GraphQL API.

You can try these changes using a development store with the 'Duties and Taxes' developer preview enabled.

For more information on how to apply duties on checkout and refund them through the GraphQL API, refer to our tutorial.

For any questions and discussion regarding the Duties and Taxes developer preview, visit our forum post.

The 2020-04 release adds parameters to better represent edited orders to the Storefront API and exposes new information about duties and taxes on international orders . Version 2020-04 also adds more information about media that has been embedded on product pages with additional fields for Product Media.

Explore all the API changes included in this release in the 2020-04 release notes.

You can also read more about API versioning in the versioning guide and on the partner blog.

Beginning today, partners who want to test orders in development stores can only process payments using the following methods: * Shopify's test payment provider (Bogus Gateway). * A payment provider set to test mode.

If you need to test your development store using real transactions, then you need to transfer your store to a paid plan.

Orders and payments in existing development stores will not change immediately. Updates to existing development stores will be announced in the developer changelog.

Learn more about test orders on the Shopify Help Center.

If you have further questions about testing payments and orders in newly created development stores, get answers in our dedicated discussion area for developers, or reach out to partner support through your Partner Dashboard.

With the evolving concerns around COVID-19’s impact on communities around the world, we know that partners and merchants are making adjustments to continue running their businesses smoothly. That’s why we’ve decided to postpone the April 1 version removal from April 1, 2020 to July 1, 2020.

This change in the timeline means that you have until July 1 to update your apps to account for changes in both 2019-07 and 2019-10 API versions. The move from page to cursor-based pagination comes into effect for all endpoints on July 1. This simplifies the migration process for apps that need to update their pagination strategies.

To see the deprecated API calls your apps are making, check out the API Health report on the Partner Dashboard.

We’ve added the following Storefront API fields to the Order and OrderLineItem objects. These new fields can be used to gain additional visibility into an order's state after an edit.

• Order.fulfillment_status
• Order.cancelled_at
• Order.financial_status
• Order.cancel_reason
• LineItem.current_quantity
• LineItem.original_total_price
• LineItem.discounted_total_price
• Order.original_total_price
• Order.current_total_price
• Order.edited
• Order.current_subtotal_price
• Order.current_total_tax

We’ve updated our Partner Program Agreement (PPA) to include new definitions of public and custom apps, and to clarify our role as a billing agent. Being a billing agent means we’re the party responsible for facilitating payment transactions between partners and merchants of apps, themes, and services.

PPA updates regarding public and custom apps are effective immediately, as communicated on our partner blog.

For PPA updates regarding the billing and tax status of some Shopify partners, we’ve made sure to provide partners with 90 days notice to assess the potential impact on how they run their businesses. As a result, the billing and tax updates to our PPA will come into effect on June 1st, 2020. Partners will begin to see product changes that reflect these billing and tax updates starting June 2020.

Partners who are impacted by these PPA updates have been directly notified by email and their Partner Dashboard.

The new API Health report on the Partner dashboard shows the deprecated API calls your apps are making, along with documentation and timelines that help keep your apps up to date with Shopify’s API versions. This tool shows details of each deprecated call including the affected endpoint and the last time a call was detected.

Learn more about the API Health report in the Shopify Help Center.

Use the customerActivateByUrl mutation to activate customer accounts without parsing the activation URL for the customer ID and token. Just send the full URL and a new password to activate the customer.

Learn more about updating customers using the Storefront API in the Shopify Help Center.

Use the customerAccessTokenCreateWithMultipass mutation to log a customer in without the email and password inputs. Send the multipass token to enable a customer and log the customer in. If a customer record does not exist in the shop, then it will be automatically created.

Learn more about how to implement a multipass token and create a customer access token using multipass in the Shopify Help Center.

With over a million stores on Shopify, it’s rare that an incident impacts every store or every service. In order to help merchants understand if their store has been affected by an incident, we’re moving Shopify's status page to a dashboard that's specific to their Shopify single sign on account.

As part of this move to store-specific status updates, subscriptions to updates (SMS alerts and RSS feed) have been deprecated. Overall status and major outages will continue to be posted to the public shopifystatus.com page.

If you are a partner or an app developer who is working with merchants on projects that require status information, such as launching ads for their store or troubleshooting an app, please have your clients or app users check their store-specific status page first as part of the process. Our team is currently working on ways to enable Partners to see status information for stores where they have collaboration login access from the merchant.

All qualified partners with apps listed on the Shopify App Store will soon be able to create search ads to help merchants discover their apps in the Shopify App Store.

Ads will be shown to merchants on app store search result pages, above the organic search results. You can associate your ads to specific search terms so that your ads are shown when a merchant searches for those specific terms.

Learn more about advertising in the Shopify App Store, in the Shopify Help Center.

We’ve added a new property for the article object as well as updated the behaviour of cart.attributes and the /cart/add.js endpoint.

article.updated_at

The article.updated_at property returns a timestamp defining when a blog article was updated. This allows themes to include the dateModified field within their Structured Data for SEO purposes. The date filter can be applied to format the timestamp. Learn more about the article.updated_at property in the Help Center.

cart.attributes

This existing property has been updated to hide keys with a double underscore (__) prefix from Liquid and AJAX API. Learn more about the cart.attributes property in the Help Center.

/cart/add.js

The /cart/add.js endpoint (add to cart) of the AJAX API has been updated to support adding multiple items to the cart in a single request. This previously required a complex queuing system to send multiple requests. The previous payload format is still supported, but the "multiple items" payload format is now the recommended approach. Learn more about the Ajax API in the Help Center.

The length of all newly generated Shopify app secret keys has increased from 32 to 38, adding a static prefix of shpss_, to make the secret keys easier to identify.

Existing API secrets will continue to function in their 32 character form until Shopify Partners manually regenerate them. This is the secret passed in as client_secret to https://{shop}.myshopify.com/admin/oauth/access_token to obtain an access token.

Learn more authenticating your Shopify app from the Shopify Help Center.

We are proud to announce a developer preview of our new sections theme architecture. As part of this developer preview you'll be able to:

• Define new theme frames to customize store headers and footers on different pages
• Customize page sections to create unique displays and formatting
• Create custom content sections that can be added to and removed from pages through the Shopify Admin
• Edit pages individually or globally, as master pages, with multi-page editing

This developer preview is limited to adding sections to product pages, but upcoming iterations will extend this functionality to all storefront pages. You can learn more about working with the new section architecture by visiting our Help Centre guides.

This developer preview is being released as part of our new online store design experience partner beta. In order to implement sections on product pages, you will need to edit your theme to conform to the new theme architecture. To see an example of this implementation, you can download our sections-compatible Debut theme.

For any questions regarding the online store design experience partner beta visit our dedicated forum.

You can now leverage two new app extensions to securely surface your app’s functionality on a merchant's store:

• App sections empower you to create new content sections that can be added, removed and configured right from the new online store editor
• App snippets help safely inject liquid code into a merchant’s online storefront.

You can learn more about creating both types of online store app extensions in our Help Centre.

This developer preview is being released as part of our new online store design experience partner beta. By participating in this beta you will be able to explore and test a number of new theming features, provide feedback and prepare and update your own custom themes with the new sections architecture.

For any questions regarding the online store design experience partner beta visit our dedicated forum.

You can now preview our new online store design experience. Through this preview you will be able to:

• Install our sections-compatible Debut theme and test new sections on product pages (all page types will be supported in the near future).
• Add, remove, and configure sections on product pages through the new online store editor.
• Explore our new online store editor to customize pages and sections within the Shopify Admin.

You can learn more about the online store design experience partner beta by reading our forum announcement.

If you have any questions or feedback about supporting this new online store design experience in your apps or themes, feel free to reach out to us in our dedicated discussion thread or through your partner dashboard.

With the release of the 2020-04 version of the Storefront GraphQL API, you can now access your inventory quantity if needed to build your shopping experience.

This information is hidden by default, but if you want to enable it, simply navigate to the private app and select the new checkbox for “inventory quantity” under the Storefront API section.

The Shopify Theme Inspector for Chrome is a Chrome DevTool plugin that lets you benchmark your Online Store’s Liquid performance, pinpoint Liquid performance issues in your theme, and test improvements for faster server response times.

• This tool helps you visualize results as a flame graph which is readable and easy to understand.
• You can examine the flame graph nodes to localize performance issues down to the exact file and line.
• A code snippet link will open up to the exact line of Liquid in your admin code editor so you can view and edit the code in context.

If you'd like to learn more, contribute a feature, open an issue, or make a feature request, check out the Shopify Theme Inspector Github repository.

Searchable resources for our predictive search API now include collections.

Read more about the predictive search API in the Shopify Help Center.

The 2020-01 release contains many of the features we previewed at Unite 2019. The product media, order editing, and fulfillment orders features are now stable and available on merchant stores. You’ll also find new additions to how you can manage smart collections and discount codes.

Explore all the API changes included in this release in the 2020-01 release notes.

You can also read more about API versioning in the versioning guide and on the partner blog.

With the release of the 2020-01 version of the REST Admin API, a new Collection API is available with the following features: * Get the products in a collection * Get a collection by its ID

Learn more about the Collection REST Admin API in the Shopify Help Center.

The Predictive Search response has been updated to include additional image details. These are all grouped under featured_image and include the following fields: * featuredimage[:alt]: the image alt tag * featuredimage[:width]: the image width * featuredimage[:height]: the image height * featuredimage[:aspectratio]: the image aspect ratio * featuredimage[:url]: the image url

Read more about the predictive search API in our Help Center.

Order editing is now available to select Shopify merchants. To help you extend this feature, we’ve published a set of order editing APIs to the release candidate of version 2020-01.

What’s included?

• GraphQL mutations that allow you to add and remove line items, as well as adjust line item quantities.
• An order/edited webhook that describes what's changed during an order edit.

Learn more about how to edit orders using GraphQL in the Shopify Help Center.

We’re putting safeguards in place for future Shopify public apps and introducing a new type of custom app.

No existing apps will be affected by this release.

Read more on the Shopify Web Design and Development blog.

Unit prices and the measurement information related to their generation is now available through the Storefront API as part of the release candidate (2020-01). The unit price feature associated with these fields is currently available to select Shopify merchants.

The following new fields were added to the product variant object:

• presentmentUnitPrices
• unitPrice
• unitPriceMeasurement

Learn more about these fields in the Shopify Help Center.

We’ve added a new global object and some new properties to Liquid, which are currently in production for all stores.

request.page_type

The request.page_type property returns the type of the current page, for example, product, article, and index.

Learn more about the request.page_type property in the Help Center.

routes

Generates URLs to your storefront. By using routes instead of hardcoded links, you can make sure your theme supports any changes to the URL format.

Learn more about the routes global object in the Help Center.

product.options_by_name

Gives direct access to a product' option values by using the option name.

Learn more about product.options_by_name property in the Help Center.

allow_false

The default filter now accepts an allow_false argument. You can use allow_false to set a default value for any variable with no assigned value. This can be used with strings, arrays, and hashes.

Learn more about this filter in the Help Center.

The Buy Button cart component’s model is no longer initiated to an empty checkout. Instead, the model is null until a variant is added to cart. This is expected to have a positive impact on the performance on your Buy Buttons!

If you have leveraged the cart’s model in any custom code written using Buy Button JS, it is recommended that you verify your Buy Button still functions as expected.

Learn more about these changes by reviewing the pull request on Github.

Errors in GraphQL responses now contain extra metadata under the extensions key. The error format follows the GraphQL specification.

The most notable metadata is the code property which returns the error code. This feature allows you to more easily match on the types of errors without having to match on the full error message.

For example:

{
  "errors": [
    {
      "message": "Internal error. Looks like something went wrong on our end.",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "requestId": "d2f47302-8559-4961-9a5b-3de60172aa29"
      }
    }
  ]
}

Searchable resources for predictive search APIs now include pages and articles. Author, body, tag, variant SKU & barcode attributes have also been added to searchable fields for products.

Parameters are getting an update (the old parameters remain valid):

• - the s query parameter is renamed to q
• - the bury option of the unavailable_products parameter is renamed to last
• - types is renamed to type and accepts a comma-separated list instead of an array
• - a fields parameter was added

By default, unavailable_products is set to last. This means that out of stock products will now be shown last in the results list. There are options to hide out of stock products completely, or show them together with available products.

Learn more about the predictive search API in the Shopify Help Center.

Buy X Get Y discounts now support setting a minimum purchase amount to qualify for the discount. This option can be used instead of requiring a specific quantity of items a customer must buy. Use this new option to create promotions such as “Spend $100, get a free gift,” or “Spend $200 on skincare, get 50% off a water bottle.”

This option is available as both an automatic discount or a discount code using the Discounts GraphQL API.

You can learn more about this new option in our Discounts API Guide in the Shopify Help Center.

You can now retrieve large amounts of data from our Admin GraphQL API using bulk operations. Provide a standard GraphQL query to the bulk mutation and you receive a link to a file that contains all of your data after the operation has finished running.

Find out more in the bulk operation guide.

Version 2019-10 is stable and ready for general usage.

Querying a product's collections is now faster because we've optimized how we build the connection between a product and its collections.

Since this is a new way of building out connections and their associated cursors, you won't be able to use a cursor from a previous version of the API. Use the same workflow as today with the 2020-01 API version to unlock these performance gains.

As of September 14, 2019, the Revised Payment Service Directive, also known as PSD2, will be implemented in all countries in the European Economic Area (EEA). PSD2 requires most online transactions within the EEA to have customer authentication. To be compliant, Shopify will process credit card transactions in the EEA by using 3D Secure, which is a payment authentication method.

If your app or sales channel implements either the Checkout API or the Storefront API, consider updating it to the 2019-10 release candidate API version of the Checkout API or Storefront API so that it can fully support payment authentication using 3D Secure.

To learn more about changes that you can make to support 3D Secure, refer to Authenticating payments with 3D Secure.

We’ve added support for automatic discounts to Buy Button carts, which has been enabled by default in the latest version of Buy Button JS.

You can now create a listing in any language that your app supports, and you can also select any language to be your primary.

We understand the importance of staying up to date with the many changes to Shopify and the Partner Program. To make sure updates are visible while not getting in the way, we’ve added a notification section to the Partner Dashboard. Over the next while, we’ll start transitioning relevant notifications from emails and banners to this section of the dashboard.

The default sorting for category pages have been updated to be ‘Most relevant’ for merchants, similar to search.

The Shopify App Store is now available in Malay Hindi, Danish, Finnish, Swedish, Thai, Korean. You can now create a listing in these languages that will be shown to merchants. Learn more about translated listings

We've added new properties on cart items listed in the JSON response of Shopify's AJAX API. Each cart item listed in the items array has the following additional properties.

• featured_image: an object with the varaint image's alt text, aspect_ratio and url.
• options_with_values: an array of objects with each product option's name and value.
• product_has_only_default_variant: a boolean describing if the product only has a default variant.

This gives theme developers more information about cart items when working with the AJAX API to build storefront designs.

To learn more about interacting with the cart through AJAX calls, read about the Shopify's AJAX API in the Shopify Help Center.

You can also read about these new properties' Liquid equivalent in the line_item object in the Shopify Help Center.

In April 2019, we introduced versioning to the GraphQL and REST Admin APIs. Today, stable version 2019-07 is now generally available. The Storefront API has also been added to our versioning scheme.

We have removed the featured field from Collects. This field will no longer be available in Admin REST API queries returning collects.

See the collects API for a list of affected endpoints.

The Liquid cheat sheet is updated to reflect the content of the Liquid reference.

The major update has been to the filters and objects, with 38 and 133 items being added respectively.

• 176 items have been added in total.
• 22 items have been edited or updated.
• 9 deprecated items have been removed.

This represents a 43% increase in content; with the filters, objects, and tags increasing from 485 items to 695.

Check out the Liquid cheat sheet in the Help Center.

We’re excited to announce the launch of private metafields. Private metafields are a new type of metafield that enables you to restrict metafield data visibility exclusively to you own apps.

We’re releasing a new Discounts API that has the ability to create and manage automatic and code discounts in the Shopify GraphQL Admin API.

You can now leverage the GraphQL Admin API to implement billing for your app.

You can now add product suggestions to storefront search by using the Predictive Search API. This shows matching products to customers immediately as they start entering search queries, and lets them easily view the related product pages by selecting items from the search menu.

We are excited to announce that after its success for Plus merchants, Multi-Currency for Shopify Payments is coming to all plans.

We’re excited to announce that Shopify now supports the ability to seamlessly sell in multiple languages using apps. This feature will allow merchants to sell with the same consistent shopping experience for international buyers in multiple languages. In order to help partners offer a fully multi-language experience and localize their apps workflows, Shopify is launching a set of new platform capabilities.

We're excited to announce the developer preview and API for managing 3D and video on products is now available to partners for testing and development. Likewise, additions to the GraphQL Admin API allow developers to create, retrieve, update, and delete 3D and video on products.

The new tax exemptions property is available on the customer resource in the 2019-07 release candidate. This allows app developers to specify which taxes a customer is exempt from paying on their orders. Tax exemption related UI changes to the admin are also exposed in the Unite developer preview on development stores.

The Fulfillment Orders API is now available. Fulfillment applications can opt into using this new API to gain new capabilities in managing fulfillments via the API. Fulfillment Orders related UI changes to the admin are also now available in the Unite developer preview on development stores.

Per product shipping has come to Shopify. Through Shipping Profiles, merchants can group products together to specify custom shipping rates for them. Apps can leverage the Delivery Profiles API to read and modify these profiles.

You can now create a translated app listing for all languages the Shopify App Store is available in. Merchants will see the listing based on the language they are browsing, if available.

We've opened up the ability for any published Shopify marketing app to be embedded directly into the Shopify admin through the marketing activities API.

You can build your own app extension today to be on the list of marketing integrations.

You can find more information about creating an app extension using the marketing activities API in the Shopify Help Center At a high level, the implementation requires the following steps.

If you have any questions about this update, then contact support through your partner dashboard or request support in our Shopify APIs and SDKs discussion board.

You can now specify Shopify Point of Sale as an install requirement for your app, to ensure that merchants can only install your app if they use that sales channel.

Shopify now supports shared web creditials between iOS apps and their website counterparts.

Shared web credentials let iOS users access a native app after logging into the respective website in Safari without re-entering their username and password. Now your customers can move between your mobile website and native app more seamlessly!

Learn how to get started in the Help Center.

We're making a change to how variants are matched based on any given options when you update products. Although we don't expect this change to impact existing apps, please review the following information to make sure that your own apps don't include any use cases that might be affected.

We've updated the Stores section on the Partner Dashboard to make it easier for you to manage all the stores you work on in one place

Theme section schemas now accept a tag attribute, which customizes the HTML tag that wraps theme sections. Existing theme sections continue to use <div> by default.

Learn more about section schema tags in the Help Center.

We’re excited to share a number of exciting improvements that we've made to the Storefront API to enable you to build custom storefronts on Shopify’s platform. These changes affect metafields, Shopify Scripts, and checkout with Apple Pay.

Earlier this year, we announced our new Product Recommendations APIs available exclusively to Shopify Plus plans. Today, we're excited to share that these APIs are available on all plan types. We've also added Liquid and Storefront API support so you can have more touch points to create better product discovery and customized buying experiences for your users customers.

Merchants will be shown a “Not Compatible” badge on the search results, category and collection pages if their app does not meet install requirements.

The Shopify App Store is now available in Dutch, Simplified and Traditional Chinese. You can now create a listing in these languages that will be shown to merchants. Learn more about translated listings

Shopify Flow connectors can now include Shopify properties in workflow triggers. You can add an order, product, or customer property, which passes all Shopify data related to that resource to the workflow.

As of April 9th 2019 we have introduced versioning of our GraphQL and REST Admin APIs and a new developer preview feature for partners.

The AJAX API has been updated to support multi-currency for Shopify Payments. This means that monetary values are now returned in the customer's cart currency.

The InventoryItem resource now includes a field requires_shipping to indicate whether the item requires shipping, deprecating the corresponding field on the ProductVariant resource.