Developer changelog

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.

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

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

At this year's Unite conference, we announced that we wanted to make some sweeping changes and improvements to the Storefront API. With the 2021-10 release, we are taking the first steps towards that goal.

Improved lookup fields

You can now fetch a Product, Collection, Page, or Blog by its handle or ID:

query FetchProduct {
    product(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzEK") { ... }
    # OR
  product(handle: "my-cool-shirt") { ... }
}

With the introduction of these new fields, the following fields are now deprecated and will be removed in a future release:

• QueryRoot.blogByHandle
• QueryRoot.pageByHandle
• QueryRoot.collectionByHandle
• QueryRoot.productByHandle

For more details, please see https://shopify.dev/api/storefront/reference/common-objects/queryroot?api%5Bversion%5D=2021-10#fields-2021-10.

Introducing OnlineStorePublishable

In order to improve consistency among objects with common properties, we have added a new GraphQL interface type named OnlineStorePublishable. This interface is used to denote a resource type that can be published to the Online Store sales channel, such as Product, Collection, Page, and others.

{
  collection(handle: "staff-picks") {
      onlineStoreUrl
    }
}

As a result, the following fields are now deprecated and will be removed in a future release:

• Page.url
• Blog.url
• Article.url

More information about OnlineStorePublishable can be found here.

Upcoming changes to object IDs

One of the most consistent pieces of feedback we've received revolves around a subtle but impactful difference between how object IDs are represented in our Admin and Storefront GraphQL APs.

You may have noticed that on the Storefront API, the values for object IDs are Base64 encoded, and furthermore, the decoded value is identical to the Admin API's response. We understand that this slight difference has proven to be problematic for developers who need to inter-operate between the two APIs.

Starting on January 3, 2022 we will begin serving non-encoded object IDs from the unstable version of the Storefront GraphQL API, with the goal of having the 2022-04 release be the first stable version that does not serve Base64 encoded object IDs.

Refer to this guide for more details on the change and how to migrate your apps.

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

As of API version 2021-10, the full permission is no longer a potential value of the permissions property on the REST User resource. This update follows the change to API version 2021-07, which returned a complete list of explicit permissions for a user.

For more information about this change, visit 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, 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.

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.

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.

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.

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.

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.

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.

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.

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

In order for theme sections to accept app blocks, the section must define a block of type @app in its schema.

A number of development shops have been created using a pre-release version of Shopify's Dawn theme. The pre-release defines blocks of type @global in some of the sections (sections/apps.liquid, sections/main-product.liquid) to indicate that those sections support app blocks.

Moving forward, @global is removed and being replaced by @app. For more information about the @app block type, refer to add support for app blocks to sections. In order to make sure your theme sections work correctly, follow one of the recommendations:

• Download the latest version of Dawn and upload it to your store.
• Update the affected theme sections to use the @app instead of the @global block type.

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.

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.

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.

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.

You can now validate a draft version of a theme app extension using Theme Check.

You can validate the content and structure of your extension by running shopify extension check in your theme app extension's project directory. Version 2.1.0 of Shopify CLI is required to run this command.

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.

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.

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.

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.

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

Learn more about Development Themes.

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

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

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

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

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

We’ve also made other notable improvements to Liquid:

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

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

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

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

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

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

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

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

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

Learn more about theme app extensions.

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

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

View the Dawn repository on GitHub.