Developer changelog

Channel Attribution is now available in beta.

Passing the correct information to these fields will now improve the accuracy of order source reporting up to the sub-channel level as well as reduce the time merchants spend organizing and fulfilling orders from marketplaces.

API reference

The following fields are now being used for sales attribution on the Orders, Checkout, and Draft Orders APIs. Please ensure that the version of the API you are using is unstable.

Orders & Checkout API Fields * source_name (String) - Handle indicating where the order originated. Can be set only during order creation, and is not writeable afterwards. Values for Shopify channels are protected and cannot be assigned by other API clients: web, pos, shopifydraftorder, iphone, and android. Orders created via the API can be assigned any of the handles from the list of accepted handles. Please note that the handles are case sensitive. If the string is not on the list of accepted handles, then the order will be left unattributed. If unspecified, then new orders are assigned the value of your app's ID. * source_identifier (String) - The id belonging to the original order. * source_url (String) - A valid URL pointing to the original order on the originating surface. This URL will eventually be displayed to merchants on the Order Details page. If the URL is invalid, it will not be displayed.

Draft Orders API Fields source_name (String) - The handle indicating the order’s origin. This field is not writable afterwards so please consult the list of accepted handles beforehand. If your handle does not exist within the list of accepted handles, the value will still be saved and will not block order creation.

Note: Please include the Content-Type param in the header ("Content-Type: application/json")

Merchants can use the Subscription API if they have Stripe on their Shopify checkout or have permission to do so.

For more information, refer to subscriptions.

On January 5, 2022, we will add a Regulatory operating fee field to the Partner payout and app earnings CSV.

This field will help app and theme developers understand the calculation of the Regulatory Operating Fee introduced in the Partner Program Agreement update. It represents the amount deducted from your app and theme charges to merchants based on the applicable merchant business address.

For more information about the Partner Program Agreement update, refer to our PPA update FAQ.

For more information about tracking your Partner earnings, visit the Shopify Help Center.

API calls made to the Admin and Storefront API are denied access if the API client does not have the required access scopes or the user does not have the required permissions. From 2022-01, when access is denied, the required permissions is returned as part of the error message. An error code is also returned.

We’ve added two new fields to the Product object, standardizedProductType and customProductType. The standardized type is a new data primitive that links products to the Shopify Product Taxonomy. We use this today to determine product eligibility for the Shop app and as a part of our BFCM Notebook. We will see future experiences using the standardized product type. The custom type provides further granularity than the standardized type allows.

For more information on Product Taxonomy, visit our developer documentation.

As of the 2020-10 version of the GraphQL API, a new field is now present on the SuggestedOrderTransaction object: supportedRefundType. This field can contain one of two values, either CARD_NOT_PRESENT_REFUND or CARD_PRESENT_REFUND.

Because "card present" refunds can only be processed by the POS that has access to the physical card, API clients only receive a SuggestedOrderTransaction by default if the supportedRefundType is CARD_NOT_PRESENT_REFUND.

For more information about SuggestedOrderTransactions, visit our developer documentation.

As of GraphQL Admin API version 2022-01, the ProductVariant object has a new field: sellableOnlineQuantity. This field returns the total sellable quantity of the product variant for online channels.

Learn more about this API on Shopify.dev.

As of GraphQL Storefront API version 2022-01, the ProductVariant object has a new field: barcode. This field returns the barcode value (ISBN, UPC, GTIN, etc.) associated with the variant.

Learn more about the barcode field on Shopify.dev.

As of GraphQL Storefront API version 2022-01, the Shop object has a new field: subscriptionPolicy. This field returns the subscription policy associated with the shop.

Learn more about the Shop object in the Storefront API documentation on Shopify.dev.

As of GraphQL Admin API version 2022-01, we are releasing a new mutation orderInvoiceSend. This mutation will take an Order ID and an EmailInput and send the order invoice to the email. It returns the Order when successful.

Learn more about this API on Shopify.dev.

Starting in version 2022-01, the BULK_MUTATION_USER_ERROR_CODE error code for the bulkOperationRunMutation mutation has been replaced by more granular error codes.

For the list of new error codes, refer to the GraphQL Admin API reference.

As of API version 2022-01, you can query for metafieldDefinitions on Order, Collection, and Customer. Previously this was only available on Product and ProductVariant.

Metafield Definitions are used to define a namespace, key, and type across all instances of a type of resource. These definitions enable Admin UI so that merchants can edit these fields in the context of each resource. You can learn more about Metafield Definitions in the Developer Docs.

This new endpoint takes an array of specific resource GIDs, and returns a list of TranslatableResources associated with those GIDs.

Learn more about the translatableResourcesByIds query and the Translations API on shopify.dev.

Shopify Markets is a cross-border management tool that helps merchants identify, set up, launch, optimize and manage their international markets - all from a single store. You can now enable a developer preview to access Shopify Markets on new development stores.

Learn more about this developer preview.

Learn more about Shopify Markets.

We've added subscription support for dynamic and accelerated checkout methods for PayPal Express on some stores.

Learn more about subscriptions in the Shopify Developer documentation.

If available, the language and country/region codes of a customer can now be appended to locale fields to provide more granularity for our partners. Affected fields are Order.customerLocale and Customer.locale in the GraphQL Admin API. For example, if a customer places an order in the french language within the France storefront of the shop, then the Order.customerLocale and Customer.locale fields will have fr-Fr.

For more information, refer to the Order and Customer object fields.

As of GraphQL API version 2021-10, running the CustomerPaymentMethodRevoke mutation can now set the customer_payment_method.revoked_reason field to manually_revoked.

For more information, refer to CustomerPaymentMethodRevocationReason.

The limit for JSON templates is increased from 50 per template to 1000 per theme. After this limit is reached, you can't create more JSON templates on the theme.

Learn more about JSON templates in the Shopify Developer documentation.

We’ve added support for contract notes to the 2022-01 API version. Contract notes are carried over from order notes on the initial order, if present.

For more information, refer to the release notes.

Media objects in the Admin API now includes mediaWarnings which returns information about a media item that might require attention such as when a 3D Model is incorrectly scaled. Data about the warning can be retrieved using the associated MediaWarningCode and message string.

Model3d objects now include a new field boundingBox that returns a Model3dBoundingBox object. The bounding box of the 3D model is the size of the model described by a box that surrounds the model.

[MediaErrorCodes](https://shopify.dev/api/admin-graphql/2021-10/enums/MediaErrorCode) and FileErrorCodes will now include a new enum value named MODEL3DPROCESSINGERROR that is used for when 3D models fail to process after being uploaded to Shopify.

Previously, the Cart API's bundled section rendering operated in the context of /cart when no specific sections_url parameter was set. Now, when sections_url isn't set, sections are rendered in the context of the current page, based on the Referer HTTP request header.

The behavior when sections_url is set remains unchanged.

For most themes, this change won't be disruptive. If the section being requested exists in the context of the current page, then using the Referer as the context for rendering, instead of /cart, shouldn't present any issues.

For more information on bundled section rendering, refer to the Ajax API's Cart reference.

Adding responsive images to your theme is now easier with the new image_tag filter. The filter outputs a responsive HTML img tag by default, allows adding arbitrary HTML attributes, and supports preloading.

Learn more about the image_tag filter on Shopify.dev.

Validation to identify vulnerable passwords has been added to the Storefront API's customerReset and customerResetByUrl mutations.

Now, when you try resetting a password to one that’s considered vulnerable, the API will return an error.

We’ve just released Marketplace Kit, a collection of APIs, components, and pre-built code snippets to add commerce features to any platform.

A marketplace is a purchasing surface on any platform, featuring products from different stores and directing buyers towards a sale. Marketplace Kit uses a channel app to connect Shopify merchants to any platform, and the Storefront API to power the set of actions that a customer can perform in a marketplace - such as viewing products and collections, adding products to a cart, and checking out.

Learn more: shopify.dev/marketplaces

The WebhookSubscription GraphQL object now has a privateMetafieldNamespaces field. You can use this field to specify private metafields that you want to be included in the payload for events sent by that webhook subscription.

The Shopify Online Store app for GitHub lets you associate a GitHub account with your Shopify login to sync changes to your themes continuously for faster development.

We are expanding this integration with GitHub to simplify the future development experience for building and deploying custom storefronts. In order to support this functionality we require additional permissions: Admin, Deployments, Pull requests, Secrets, and Workflows. The GitHub app will only require these permissions to work with custom storefronts.

We are asking for the minimum GitHub app permissions that we require to build a smooth experience for you. Ignoring this request won’t affect your work with the Online Store channel, and you can always come back to grant the permissions as needed.

Learn more about the GitHub integration with Shopify from Shopify Developer docs.

We have changed part of the AbandonedCheckout GraphQL API visibility to public. Third-party apps only have access to the AbandonedCheckout object and a selection of its fields if the marketing_automation_abandonments beta flag is enabled for the app. The available fields are line_items, line_items_quantity, and total_price_set.

The following types of storefront filters on product and variant metafields are now supported:

• single_line_text_field
• number_decimal
• number_integer

Learn more about storefront filters on metafields in the Shopify Developer Docs.

We've added a new CustomerPaymentInstrument and CustomerShopPayAgreement to the 2021-10 API version that allows the ability to store Shop Pay Agreements in Shopify to be used by SubscriptionContracts.

We’ve just launched the Payment Terms API to allow you to build apps that can set due dates on an order and track overdue payments with the newly added overdue status.

Payment terms and overall payment flexibility are important to Shopify merchants, especially those selling B2B, as they allow merchants to improve their buyer experience by offering personalized payment options and reduce the manual effort required to manage and process payments due at a later date.

Learn more about the Payment Terms API and view our release notes.

External apps can now subscribe to a webhook event to be notified when a financial institution challenges a subscription billing attempt charge. This update is in accordance with 3-D Secure.+

The webhook event will trigger a message to be published on the subscription_billing_attempts/challenged topic. To use the topic, an app requires the own_subscription_contracts access scope.

For more information, visit the REST Admin API Webhook documentation.

As of API version 2021-10, you can use the bulkProductResourceFeedbackCreate mutation to create up to 50 feedback entries on a product resource in a single API request. You can also query for product resource feedback with the productResourceFeedback field.

For more information, refer to https://shopify.dev/api/admin/graphql/reference/apps/bulkproductresourcefeedbackcreate

API version 2021-10 adds the origin_address property to the REST Admin API's Fulfillment resource. origin_address specifies the address at which a fulfillment occurred.

origin_address accepts a JSON object with address1, city, zip, province_code, retail, or country_code.

For more information about Fulfillment, visit our developer documentation.

As of API version 2021-10, the TranslatableResourceType enum will include two new resource types: ONLINE_STORE_MENU and PACKING_SLIP_TEMPLATE. ONLINE_STORE_MENU refers to the links used for navigation on an online store. PACKING_SLIP_TEMPLATE refers to templates used for creating packing slips. The ONLINE_STORE_MENU's title field and PACKING_SLIP_TEMPLATE's body field are now translatable with our translations API.

Learn more about this API on Shopify.dev.

As of the 2020-10 version of the GraphQL API, a new field is now present on the CustomerPaymentMethod object: revokedReason. This field can contain one of the following values: * AUTHORIZE_NET_GATEWAY_NOT_ENABLED * AUTHORIZE_NET_RETURNED_NO_PAYMENT_METHOD * FAILED_TO_UPDATE_CREDIT_CARD * STRIPE_API_AUTHENTICATION_ERROR * STRIPE_API_INVALID_REQUEST_ERROR * STRIPE_GATEWAY_NOT_ENABLED * STRIPE_PAYMENT_METHOD_NOT_CARD * STRIPE_RETURNED_NO_PAYMENT_METHOD

Updated the customerPaymentMethod API to allow querying for a reason on why a payment method was revoked.

For more information about CustomerPaymentMethod, visit our developer documentation.

As of API version 2021-10, the Order object will include an app field representing the application that created the order. The field returns an OrderApp object.

Learn more about this API on Shopify.dev.

As of API version 2021-10, the line_item object on a Fulfillment will include a fulfillment_line_item_id property. This property represents the ID of a line item from an order that's included in a fulfillment

Learn more about this API on Shopify.dev.

Apps can now subscribe to the bulk_operations/finish webhook topic that sends notifications when a Bulk Operation has completed, failed, or been cancelled.

Apps do not need to poll the GraphQL Admin API to check for status changes anymore. The webhook will notify the app when the Bulk Operation finishes.

This webhook supports query and mutation operations.

Learn more about the new feature in the Bulk Operation tutorial and the API documentation.

The BulkOperation object has a new type field that returns whether the operation is a query or a mutation.

Learn more about the type field in the BulkOperation object documentaion.

As of the 2021-10 API version, we have introduced a customerPaymentMethodGetUpdateUrl mutation to the Admin API that, given a customer payment method ID, returns a URL that enables a customer to update their payment method in a secure way when in a session. This mutation supports Shop Pay as of late 2021, and will expand support to other payment methods in the future. The customerPaymentMethodSendUpdateEmail is recommended as a fallback when the customerPaymentMethodGetUpdateUrl returns an error or when the customer needs to update their payment method outside of a session.

Learn more about this mutation by visiting our developer documentation.

As of API version 2021-10, you can query prices given a particular context using the new field contextualPricing . This functionality allows Apps to query prices in different contexts, including prices for countries (International Pricing). This new field was added to the Product Variant object to return a price and to the Product object to return a price range.

Learn more about the Contextual Pricing API on Shopify.dev.

You can now take advantage of preload links in Liquid by using the preload_tag filter. The filter will add a link tag with rel=preload to the page, and will attempt to add an entry to the response's Link header.

Learn more about the preload_tag filter in the Shopify Developer Docs.

As of API version 2021-10 Sales Channels can now complete a checkout with the Storefront API using TokenizedPaymentInputV3 and the PaymentTokenType value STRIPE_VAULT_TOKEN

Learn more about completing a checkout with the Storefront API and refer to the TokenizedPaymentInputV3 fields documentation on Shopify.dev.

In limited circumstances, such as when using cart permalinks, customer details like email and shipping address could be contained in the query parameters of the resulting checkout URL.

These customer details no longer appear in checkout URLs. Features that resulted in this behavior like cart permalinks should continue to function as normal.

You can now directly report violations of our Partner Program Agreement, instead of contacting Shopify Partner Support. Please ensure your report is a term violation rather than a support issue.

Learn more about prohibited actions on Shopify.dev

As of API version 2021-10, you can use the GraphQL Admin API and REST Admin API to retrieve, add, and update a customer's consent to receive marketing material by SMS.

You can also subscribe to a webhook topic to be notified when a customer updates their SMS marketing consent.

For more information, refer to the API 2021-10 release notes.

Shopify’s post-purchase checkout extension now supports subscriptions offers. By surfacing subscription offerings immediately after checkout, you can now start building high-converting experiences for merchants’ most captive buyers.

Learn more about getting started, requirements, and limitations for post-purchase checkout extensions.

Merchants selling on multiple channels are unable to tell how long they have to fulfill a multi-channel order in Shopify to be compliant with the fulfillment policies of the channel. This can lead to merchants being penalized by the channel, having longer processing times which impacts a merchant's ratings on marketplaces and further reduces their dependence on Shopify as their back office.

The new field, fulfill_by on the FulfillmentOrder object, indicates the latest date that a merchant should fulfill an order to ensure that it arrives to the buyer within the estimated delivery window. This is the date at the end of the longest processing time for an order.

For example, if your processing time for an item is 3-5 days, and a buyer orders the item on September 1, then the fulfill_by date for this order is September 6.

The fulfill_by field is currently available only in the unstable version of the GraphQL Admin API and the REST Admin API. They are accessible through the new OrderSetFulfillmentDeadline mutation or endpoint POST /admin/api/unstable/fulfillment_orders/set_fulfillment_deadline.json.

You can now query merchantApprovalSignals on the Shop object to determine whether a merchant is pre-verified for onboarding to channel apps.

This query helps you to accelerate the process for onboarding approved merchants to sales channels.

For more information, refer to the release notes.

We increased the maximum number of app blocks supported in theme app extensions from 10 to 25. Learn more about theme app extensions on Shopify.dev.

We've updated the terms related to the new revenue sharing plan for theme developers in our Partner Program Agreement.

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

The fulfillment service SKU sharing developer preview gives fulfillment service apps the ability to stock and fulfill product variants alongside a merchant's locations.

This preview introduces the permits_sku_sharing parameter when creating or updating a fulfillment service. Setting permits_sku_sharing to true allows the merchant to assign fulfillment orders to both the merchant's locations and compatible fulfillment services.

Learn more about this developer preview

Learn more about the building a fulfillment service using the fulfillment orders API.

Learn more about fulfillment orders on the REST and GraphQL APIs.

Starting Tuesday September 7, 2021, if you're submitting an app that integrates with a theme to the Shopify App Store, then you need to use theme app extensions.

Existing apps are strongly encouraged to adopt this feature as well. However, there is currently no deadline for existing apps in the Shopify App Store to adopt theme app extensions.

You can now show predictive search results through a rendered section using the following:

• The Liquid predictive_search object
• The /search/suggest endpoint of the Predictive Search API

Learn more about adding predictive search to your theme.

Shopify has introduced new guidelines around currency formatting for themes. If you're developing a theme, you can introduce a currency setting that lets merchants choose whether the currency code is included in price displays.

Showing the currency code with a price helps customers understand what currency they're browsing in, especially when the currency uses a common symbol like the dollar ($), so that there's no confusion at checkout.

To learn more about how this setting is implemented, and other considerations, refer to the price display UX guidelines.

Metafields now support a Rating type. Ratings represent a value on a specified scale, such as a product rating of 4.8 out of 5, or a spiciness rating of 3 chili peppers.

Learn more about Ratings in our metafield types and metafield object documentation.

As of August 2021, Shopify automatically minifies theme JavaScript when it is requested by the storefront. Minified JavaScript files are cached until the next time the underlying file is updated.

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

Learn more about theme performance on Shopify.dev.

External apps can now subscribe to SellingPlanGroups webhook events to keep track of SellingPlans and SellingPlanGroups lifecycles.

The following are the topics for the events:

• selling_plan_groups/create: Triggered when a new SellingPlanGroup is created.
• selling_plan_groups/update: Triggered when a SellingPlanGroup is updated, including adding/removing/updating SellingPlans.
• selling_plan_groups/delete: Triggered when a new SellingPlanGroup is removed.

To use the topics, an app requires the read_products access scope.

On August 1, 2021, we will introduce two changes to the Partner payout CSV and app earnings CSV. These changes will help developers understand the calculation of their app revenue after they register for the new app store revenue share plan.

The following fields will be added or updated:

• Processing fee (new) - This new field represents the amount deducted from your application's charges to merchants for processing the charge.

• Partner share (updated) - The calculation of this field will be updated to represent the Partner sale amount less the Processing fee as well as the Shopify fee. This field will now better represent the amount you earn for each app charge.

For more information about tracking your earnings, visit the Shopify Help Center.

Starting today, the following changes are effective on the unstable version of Partner API to help developers with the calculation of their app store revenue.

• The transaction objects AppOneTimeSale, AppSaleAdjustment, AppSaleCredit, AppSubscriptionSale, and AppUsageSale have a new field titled processingFee. The processingFee field indicates the amount that was deducted for processing your application’s charge to a merchant.
• The previously mentioned transaction objects have a new calculation for the netAmount field. The new calculation accounts for the deduction of processingFee amount from your app charge and adjustment to a merchant.
• SALE_SHOPIFY_FEE in the TaxTransactionType enum is deprecated and replaced by the SALE_FEES value. When taxes are charged on all fees for an app, theme, or service transaction, the SALE_FEES value is returned in the TaxTransaction object.
• The type field in TaxTransaction object is deprecated. A new field titled taxType is now present on the object, which will return either TaxTransactionType.REFERRAL_COMMISSION for taxes paid out on your commission fee for a referral or TaxTransactionType.SALE_FEES for taxes charged on fees for an app, theme, or service transaction.

These changes are available in the unstable version today and will be made official in the 2022-01 version of Partner API. Learn more about partner API reference documentation at Shopify.dev.

Starting August 1, 2021 at 10:00 am PST (1:00 pm EST), app developers can register for a reduced revenue share plan for apps sold through the Shopify App Store in the apps section of the Partner Dashboard.

In this new plan, Shopify collects 0% on the first 1,000,000 USD in annual gross app revenue earned through the Shopify App Store. Total app revenues in excess of 1,000,000 USD annually will be subject to a 15% revenue share, reduced from the previous 20%.

Learn more about updates to revenue share for Shopify App Store developers in the Shopiry Help Center.

We've updated the following items in our Partner Program Agreement:

• Terms related to the new revenue sharing plan for app developers
• Administrative details that help support the growth of Shopify Partners

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

As of API version 2021-07, you can use the GraphQL Admin API and Google Cloud Pub/Sub to subscribe to, update, and delete webhook subscriptions.

You can learn more about managing webhooks with Google Cloud Pub/Sub at Shopify.dev.

As of July 2021, you can use the BulkOperationRunMutation endpoint, a resilient and performant solution, to move data in bulk into a store in a bulk asynchronously.

Instead of running a GraphQL mutation multiple times, you can run a bulk mutation operation. This is a simple way for you to import all of their data, without being slowed down by throttles.

We currently provide support for the following mutations: * productCreate * collectionCreate * productUpdate * productUpdateMedia * productPageUpdate * productVariantUpdate * metafieldUpsert * priceListFixedPricesAdd * priceListFixedPricesDelete

Learn more about how to get started with Bulk Mutations.

As of version 2021-04 of the REST Admin API, the Checkout resource returns the application_type property for discounts that are added to a checkout. The field shows how the discount was applied. Valid values are automatic, discount_code, manual, and script.

To learn more, refer to the Checkout reference.

Metafields are currently available to Products and Product Variants in the unstable API version. When the stable API version 2021-07 is released, the Metafields will also be available to Shop Collections, Customers, Blogs, Articles and Pages.

When merchants sell on multiple sales channels, it can be difficult to determine whether the merchant or the sales channel is responsilbe for remitting sales taxes. For example, most marketplaces are the liable party for sales tax, and should be excluded from merchant sales tax filings.

As of the 2021-07 version of the REST and GraphQL orders APIs, a new field is now present on the TaxLine object: channel_liable. This field indicates whether the sales channel that submitted the order is liable for remittance for each tax line. It can contain the following values: - true indicates that the channel is responsible for remittance of the tax line. - false indicates that the channel is not responsible for remittance of the tax line. - null indicates that it is unknown who has the responsibility, and that the merchant should check with a local tax authority to determine their tax obligations.

The channel_liable field lets developers inform merchants that another party is responsible for sales tax remittance, which then helps merchants better understand the tax that they are responsible for.

As of API version 2021-07, the GraphQL Admin API returns XXX in response to an unrecognized currency code. XXX is the ISO code used to denote transactions that involve no currency.

In mutations, a CurrencyCode input value of XXX is invalid. XXX can only be returned as a result and not as an input value.

This change prevents order pages from breaking if payments include a currency code that's not in the list of [supported values for the CurrencyCode object](api/admin/reference/common-objects/currencycode).

The new Liquid input setting allows merchants to add custom Liquid code directly from the editor. The Liquid setting is similar to the HTML setting type, except it allows access to Liquid variables. This means merchants will be able to access global and template-specific Liquid objects without editing their theme code.

Learn more about this update in our developer documentation.

Refer to Dawn’s custom-liquid section for an example of how the Liquid setting can be implemented.

As of API version 2021-07, you can use the File API to create, update, and delete generic files and images. This functionality allows merchants to reuse files for different apps. These files are added to the Files page in Shopify admin.

Learn more about the File API on Shopify.dev.

With the Shopify GitHub integration, you can connect your GitHub user account or organization to your Shopify admin, and connect Git branches to themes in your store. Native support for version control allows you to make and track and manage changes to theme code, as well as collaborate with other developers and share progress in real time.

Learn more about the Shopify GitHub integration.

You can now access our post-purchase checkout extension beta. This allows you to start building high-converting experiences like upsell offers, survey, donation requests, and more.

For more information on getting started, requirements, limitations, and more, refer to our detailed developer documentation.

Theme developers can now use Shopify CLI to build themes.

You can now do the following:

• Develop, preview, and test changes using development themes
• Hot-reload CSS and Liquid section changes as you’re developing
• Initialize a new theme project using our reference theme, Dawn, as a starting point
• Push and publish themes from the command line
• Lint your theme’s code using Theme Check
• Populate test data for your theme, including products, customers, and draft orders

Learn more about developing themes using Shopify CLI.

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.

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

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.

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

The type system is exposed 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. Both fields being supported until 2021-10 when valueType will be removed.

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

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

Theme developers 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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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 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.

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.

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.

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.

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.