Developer changelog

Shops with checkout.liquid enabled can now upgrade to a new version of Shopify Checkout, unlocking powerful new checkout features—like subscription apps and local pickup—while keeping checkout.liquid customizations in-tact.

All checkout upgrades need to be completed by February 26, 2021. Shops that don’t complete the upgrade within the checkout upgrade window (January 25, 2021 to February 26, 2021) will be upgraded automatically, which may cause some checkout.liquid customizations to break.

Find instructions for the checkout upgrade process in the Shopify help center.

Note: Only shops with checkout.liquid enabled need to perform the upgrade.

If a merchant uninstalls a subscriptions app, then 48 hours later selling plans and associated records (selling plan groups, policies, and their associations to products and variants) are deleted. Subscription contracts and the product and variant records themselves won't be affected.

Learn more about selling plans in the Shopify Help Center.

Two new staff permissions have been added to the Partner Dashboard, giving you more granular control over what your organization’s staff members can access.

• View referrals grants access to the Referrals page.
• Manage affiliate campaigns grants access to the Affiliate tools page, and affiliate tools on the Referrals page. Staff members with this permission can also manage affiliate campaigns. This permission is available only to organizations that are part of the Shopify Affiliate Program.

Access to these features was previously controlled by the Manage shops permission. Staff members in your organization who have the Manage shops permission are granted View referrals as part of this update. If you are part of the Shopify Affiliate Program, then staff members who have the Manage shops permission are also granted the Manage affiliate campaigns permission as part of this update.

To learn more about staff permissions, visit the Shopify Help Center.

All developers can now request access to the Subscription APIs and Product Subscription App Extension. Using these tools, developers can build flexible apps that support new selling methods for merchants, and are compatible with all of Shopify’s platform features (including discounts, shipping, reporting, and payments).

To learn more about building with the new Subscription APIs and tooling, refer to our developer documentation.

The Checkout API no longer returns the amount of inventory remaining when a checkout is created or updated and there are not enough products in stock. This change was made to protect the privacy of our merchants.

To support older themes, the option remaining: 1 is returned from the API. However, this number doesn't change, or represent the actual amount of inventory remaining. This option will be removed in a future version of the API.

Learn more about the updated error response by reading our Checkout API documentation on Shopify.dev.

API access to App event, Earning, and Experts Marketplace Job data is now available to all Shopify Partners through the new Partner GraphQL API. This API allows programmatic access to data that was previously available only on the Partner Dashboard.

To get started with this API, visit Shopify.dev.

On the Shopify Plus plan, brands get exclusive access to the checkout.liquid file, enabling them to make flexible customizations to Shopify Checkout. However, they need to upgrade Shopify Checkout periodically in order to unlock new checkout features while ensuring any checkout.liquid customizations remain in-tact.

The next checkout upgrade will take place between January 25, 2021 to February 26, 2021. Only shops with checkout.liquid enabled need to perform the upgrade.

Learn more about the checkout upgrade process and view a full list of the new Shopify Checkout features in the Shopify Help Center.

When billing for your app, your charges and subscriptions will transition between a few different states.

One of these transitions is the accepted to active state.

When a merchant accepts a new one-time charge or subscription, the charge transitions from pending to accepted. However, the merchant is not charged until you manually activate that charge, transitioning the status from accepted to active.

To simplify the billing flow for apps and make it easier to use, we're removing the need for that request.

Starting in the 2021-01 release: when a charge is approved by a merchant, the charge will immediately transition from pending to active. Check out our updated REST Admin API billing guide for more information.

As of Storefront API version 2021-01, you can obtain the SEO details for Product, Blog, and Page nodes. This new field returns translated content if any is available.

As of the 2021-01 API version, a new field translated_name will be available in DeliveryCountry and DeliveryProvince types. The translated name of the country or province is based on the user locale.

Previously, the Users endpoint returned the full list of all staff accounts on a shop.

For shops with a large number of users, this could lead to response timeouts, as the list was simply too large to return within a reasonable timeframe.

To make this data more manageable, we've enabled the same cursor-based-pagination found in other areas of the Admin API on the Users endpoint.

To learn more about pagination support in REST Admin APIs, please check out this tutorial.

As of the 2021-01 API version, product media information in the GraphQL Storefront API is returned in order of its position.

We've made some updates to our API License and Terms of Use and our Partner Program Agreement to protect the integrity of our platform and clarify how apps should be built and distributed on the Shopify platform.

These changes come into effect as of today, January 1, 2021.

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.

In April 2020, we released a breaking change that added additional validation requiring the compare_at_price to be strictly greater than the price on variants, in order to provide a more consistent experience for apps consuming these values.

Due to an internal oversight, apps affected by this breaking change were not notified of that fact until very recently. In order to provide apps with enough time to do this migration, we are extending the migration window for this change by 1 full versioning cycle. Effectively, this change will move from 2020-04 to 2020-07.

We encourage you to stay on top of changes by regularly viewing your API Health report, checking for the presence of a deprecation header, and by reading through our quarterly release notes.

Learn more about this breaking change in the 2020-07 release notes.

You can now create customizable team permissions for Shopify App Store ads. Owners of partner accounts can now set permissions for which team members can and can’t view or manage ads, or financials.

Owners can customize ad permissions in the Team section of the Partner Dashboard. The ad permissions that you can assign to team members are View ads, Manage ads, and View financials.

• View ads allows the team member to view the ads reporting dashboard.
• Manage ads allows the team member to create and edit ads.
• View financials allows the team member to access the Ad billing page.

To learn more about ad permissions, please visit the Shopify Help Centre.

As of the 2021-01 version, we've made it easier to determine the original width and height of storefront images before attempting to download and render it. This will help with optimizing performance of client-side rendering logic, such as preventing content reflow from lazy-loaded images.

Learn more about the image width and height properties in the Shopify Storefront API documentation.

Earlier this year, Localization Extensions were launched to allow additional information to be collected upon checkout. This feature can be used to collect information for stores to meet various countries' regulatory requirements (e.g. Brazillian CPF numbers).

Version 2021-01 of the GraphQL Admin API adds functionality to update those values using an order mutation.

For more information, refer to the GraphQL Admin API reference docs for the OrderInput object and the DraftOrderInput object.

As of the 2021-01 API version, you can now proxy script tags added to Storefront's via the ScriptTags API through Shopify infrastructure, allowing Shopify's globally distributed CDN to cache and serve your script tags.

Learn more about the new cache property in the ScriptTags API documentation.

Private apps can now check their deprecated calls through the Deprecated endpoint using the REST API.

Details can be found in the REST API reference doc

The following Subscription API resources received updates:

• Descriptions updated for SellingPlanAnchor.day.
• Added the pricingPolicy field to SubscriptionLine and SubscriptionLineInput.
• Added createdAt and completedAt DateTime fields to SubscriptionBillingAttempt.
• Added nextBillingDate to SubscriptionDraftInput allowing the nextBillingDate to be batched with other changes.
• Added the expiresSoon field to CustomerCreditCard.
• Removed DELIVERY from SellingPlanRecurringDeliveryPolicyIntent.
• The subscriptionDraftLineUpdate mutation now accepts partial input. Unspecified fields retain their previous value.
• Added the customer_payment_methods/revoke webhook.
• Added the admin_graphql_api_id attribute to customer_payment_methods/*. Manually building the resource ID is no longer required.

As of 2021-01, you can query transaction fees on the OrderTransaction resource. The TransactionFee provides you with a breakdown of the fees associated with an order transaction, such as processing fees or foreign exchange fees.

Learn more by visiting the OrderTransaction and TransactionFee reference docs.

Update March 11 2021: The version was delayed to 2021-04 from the originally posted 2021-01.

Duties are now available on the 2021-04 version of the Storefront API. You can query duties on the Checkout and Order resources.

Learn more by visiting the Checkout and Order resource reference docs.

Details of resources affected:

API Version 2021-04 or later (includes duties)

Checkout

lineItemsSubtotalPrice: The sum of all the prices of all the items in the checkout. Duties, taxes, shipping and discounts excluded.

paymentDueV2: The amount left to be paid. This is equal to the cost of the line items, duties, taxes and shipping minus discounts and gift cards.

subtotalPriceV2: Price of the checkout before duties, shipping and taxes.

totalPriceV2: The sum of all the prices of all the items in the checkout, duties, taxes and discounts included.

Order

currentSubtotalPrice: The subtotal of line items and their discounts, excluding line items that have been removed. Does not contain order-level discounts, duties, shipping costs, or shipping discounts. Taxes are not included unless the order is a taxes-included order.

currentTotalPrice: The total amount of the order, including duties, taxes and discounts, minus amounts for line items that have been removed.

subtotalPriceV2: Price of the order before duties, shipping and taxes.

totalPriceV2: The sum of all the prices of all the items in the order, duties, taxes and discounts included (must be positive).

API Version 2020-10 or earlier (does not include duties)

Checkout

lineItemsSubtotalPrice: The sum of all the prices of all the items in the checkout. Taxes, shipping and discounts excluded.

paymentDueV2: The amount left to be paid. This is equal to the cost of the line items, taxes and shipping minus discounts and gift cards.

subtotalPriceV2: Price of the checkout before shipping and taxes.

totalPriceV2: The sum of all the prices of all the items in the checkout, taxes and discounts included.

Order

currentSubtotalPrice: The subtotal of line items and their discounts, excluding line items that have been removed. Does not contain order-level discounts, shipping costs, or shipping discounts. Taxes are not included unless the order is a taxes-included order.

currentTotalPrice: The total amount of the order, including taxes and discounts, minus amounts for line items that have been removed.

subtotalPriceV2: Price of the order before shipping and taxes.

totalPriceV2: The sum of all the prices of all the items in the order, taxes and discounts included (must be positive).

TL;DR - In high-volume situations, the timeout for responding to rate requests from Shopify will be dynamically adjusted based on the number of requests per minute.

The timeout for CarrierService API rate requests will be changed to a dynamic value depending on how many requests per minute (RPM) are being made by the client. This change is to optimize the performance of checkout, while still giving apps the appropriate amount of time to calculate shipping rates. These limits are applied to each app-shop pair. The new timeout values are as follows:

• RPM under 1500: read timeout will be 10 seconds
• RPM between 1500 and 3000: read timeout will be 5 seconds
• RPM over 3000: read timeout will be 3 seconds

These values are upper limits and should not be interpreted as a goal to develop towards. The requests are also treated as tiers, so only those requests above a given threshold will be given a lower timeout.

Shopify is constantly evaluating the performance of the platform and working towards improving resilience as well as app capabilities. As such, these numbers may be adjusted outside of our normal versioning timelines. The data and statistics have shown the impact to our partner community with these thresholds are minimal.

For more information on the CarrierService API, read our documentation here: https://shopify.dev/docs/admin-api/rest/reference/shipping-and-fulfillment/carrierservice

The use of .scss files within compiled Shopify themes is being officially deprecated. We'll be transitioning to only using .css files within all free and paid themes available on the Shopify Theme Store.

Support for Sass won't be removed in the short term and themes using .scss files will continue to function. However, we strongly recommend that developers compile their .scss files to .css locally, or use only .css files. New themes might be blocked from using .scss files in the future.

To learn more about this change and the alternatives available for developers who want to continue using Sass in their development workflow, refer to the Shopify Partners Blog.

As of 2021-01, apps can access Shopify Payments extended authorization fields by querying the GraphQL Admin or REST Admin APIs.

On November 2nd, we will be introducing a new collection of apps for both subscriptions and post-purchase upsells in the Shopify App Store. These are the first apps built directly within Shopify Checkout using the new Subscriptions APIs and post purchase app extensions, creating a more smooth and integrated experience.

With this release, the previous subscription apps and post-purchase upsell apps that bypass the Shopify Checkout will no longer be available for download. Merchants currently using these apps will continue being able to use them, but any new clients will need to select from one of the publicly available options that are properly integrated into the Shopify Checkout. All the most popular apps in these categories have replatformed their apps to leverage these new APIs and extensions and can be found in our new collection.

View the new collection of apps on the Shopify App Store, and learn more about the Subscriptions APIs in our Shopify developer documentation.

We've released a new version of Debut that contains the new pickup availability feature. This feature lets merchants show customers whether a product in the online store is available for local pickup. On each product page, the pickup availability section shows whether the product is available, and the estimated time frame for pickup.

Learn more about how merchants can show pickup availability from the Shopify Help Center.

Want to implement this feature in your own themes? Checkout the Add pickup availability to product pages tutorial.

To maintain a safe and secure working relationship between merchants and partners, we've added an additional layer of security when requesting access to a store through a collaborator account. Merchants can choose to set a 4-digit collaborator request code to only receive collaborator requests from those who have the exact code. If this feature is enabled, then you'll need to get the code from merchants to request access to their store.

For more information on the collaborator request code and where to enter the code in your partner dashboard, visit our documentation.

We've released a new reporting column for App store ads - relevance. The relevance column provides advertisers with a more explicit signal for how relevant their app is for any given search term or keyword.

To learn more about creating ads in the Shopify App Store, refer to our documentation.

On October 14th, we’re introducing a new ‘Charge_ID’ field in the Partner Payout CSV, so app developers can link app charges with a particular payout item. This new field will help app developers reconcile app charges with their payouts.

Note that the new Charge_ID field is only available for data generated in new Partner Payouts CSV file downloads.

For more information on the Partner Payout CSV, visit the Shopify Help Center.

We’re excited to introduce APIs and tooling that will enable you to build support for subscriptions into the cart and product pages on the storefront.

You can use the Subscription APIs and Product Subscription Extension to develop flexible apps that support new selling methods for merchants, and are compatible with all of Shopify’s platform features (including discounts, shipping, reporting, and payments).

Start developing new subscription apps today! Request access to the new APIs using our early access sign up form.

To learn more about building with the new Subscription APIs and tooling, refer to our developer documentation.

To learn how we’re making Shopify checkout more extensible for you, check out our Web Design and Development blog.

As of 2020-10, legal settings can now be modified using the new Legal Policies API. Legal policy apps will be able to update the text content of policies by specified policy type (e.g. refund policy or privacy policy).

Learn more about the all new Legal Policy API in our developer docs.

In the 2020-10 version release, the status field was added to the product resource in both the REST Admin API and GraphQL Admin API. Merchants can use the field to identify, filter, and manage products based on their current status: draft, active, or archived.

Merchants can save new products as a draft and work on them iteratively until they’re complete and ready to be made available to selected sales channels with an active status. Merchants can also archive products they’re no longer selling to keep their product list organized, free of clutter, while retaining all product information.

To learn more about product status changes, refer to our product status API guide and 2020-10 release notes.

The following fields were previously deprecated, and have now been fully removed as of 2020-10.

• Refund.restocked
• RefundLineItem.refundType

These fields were deprecated by RefundLineItem.restockType.

For more information, see the RefundLineItem object in our documentation.

As of the 2020-10 API version, you can query a shop's shipping policy using the shippingPolicy field on the Shop object.

To learn more about the shippingPolicy field, refer to our developer reference documentation.

We've updated bid suggestions to give advertisers a more accurate view into what bid is required for their app to be competitive for any given keyword. Bid suggestions take into account your current relevance score when surfacing a suggested bid range.

• For exact match keywords, the likelihood that your ad will show up on the first page of search results increases.
• For broad match keywords, the competitiveness against other advertisers who bid on that keyword is measured.

To learn more about creating ads in the Shopify App Store, refer to our documentation.

Due to low usage, as of September 30th we no longer support AdRoll on Shopify App Store listings. For remarketing, we offer alternatives such as Google and Facebook Pixel support.

Learn more about setting up app listing tracking and retargeting from the Shopify Developer documentation.

We've made improvements to the rich text editor for Blogs posts, Pages, Products and Collections. You can now manually add RGB/HEX codes into the rich text editor with the new color picker, making it easier to precisely match text and background color to your brand and style.

Learn more about using the rich text editor from the Shopify Help Center.

The customer privacy API is a browser-based, Javascript API that enables developers to read and write cookies related to a buyer's privacy preferences. As of 2020-10, the API is available to all Shopify online stores as a property on the global window.Shopify object.

For more information on the new Customer Privacy API, visit our developer documentation.

As of 2020-10, apps can now add manual or percentage-based discounts to any item that is added while editing an order with the GraphQL Admin API.

For more information about using discounts with order edits, including the specific mutations to add discounts, visit the tutorial on editing an existing order with the Admin API.

The theme editor has been rebuilt in React and includes an updated mobile theme editing experience and many UI enhancements. The rebuild also decreases load times for large themes, making it easier and faster for merchants to set up and customize their online store, while also laying a new foundation for future improvements to the theme editing experience.

Update 9/25/2020: If you provide an app that detects usage in the Theme Editor, then please ensure that you’re using the official JavaScript API, Shopify.designMode, to detect the Theme Editor. Other implementations involving detection of the URL could cause broken experiences for merchants. For more information please review the community forum or the partner discussion area.

To learn more about the new theme editor, please visit the Shopify Help Center.

As of the 2020-10 API version, apps can add an array of media objects to product variants. Currently the array is limited to only one media object of type image.

For more information on how to work with product variants and media using the GraphQL API, refer to our variant media tutorial.

Additionally, we've added a new mime type field to the MediaImage object in the GraphQL API.

As of the 2020-10 REST API, checksums will be provided on assets that were recently updated.

If you use a client that supports checksums (ie Theme Kit 1.1 or newer), then the time it will take to sync your local files and the bandwidth used will be drastically reduced.

For more information, please see the checksum field in the REST API.

Please also see the blog post: How We Improved Theme Development Tooling Using Checksums

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 want to test your development store using real transactions, then you can select and purchase a Shopify plan in the account settings of your development store.

This change was applied to all newly created development stores on March 30, 2020, as mentioned in our changelog update here. Beginning September 14, 2020, this change will be applicable across all development stores.

Learn more about test orders in the Shopify Help Center.

You can now subscribe to Shopify Payments dispute events with webhooks. The disputes/create and disputes/update topics are now available in all supported API versions.

For more information, visit the webhooks topic documentation.

Version 2020-10 of the GraphQL API will now allow you to directly query an order that is associated with a given refund.

For more information about the Refund object, visit our developer documentation

Earlier in the year we released the ability to refund duties using the GraphQL API. Now, as of version 2020-10, we are releasing the same functionality on the REST API.

For more information, please see the refund_duties property in the REST API.

With the release of international domains, shops can now assign a country and language to individual domains. As of 2020-10, a shops eligibility for international domains can be determined via the internationalDomains field.

For more information, please see the GraphQL API documentation.

Please note that before you redirect a shop to an enabled language you should first check internationalDomains and domain localization to confirm which languages are available on which domains.

Failing to do so and redirecting to a domain which doesn't support the language would result in a 404.

Apps can now get additional context about batch discount code creation errors by looking into the new logs field. This field will return any error the system reported when trying to create the discount codes based on the price rule definition.

To learn more about this new field, visit the reference documentation.

We've added some new features to Discounts on the GraphQL Admin API, including:

• Usage counts for automatic discounts.
• New ways to search through discounts.
• Speed up the management of discounts with bulk mutations!

We've also deprecated the type filter parameter on CodeDiscountQuery. Use discount_type instead.

For the full list of changes, see the 2020-10 release notes.