Developer changelog

Two new input setting types have been added to the theme editor: product_list and collection_list. They allow merchants to quickly create curated, ordered and paginatable lists of products and collections.

Learn more about product_list and collection_list on shopify.dev.

As of GraphQL Admin API version 2022-04, an error returns when a metafield definition is created with invalid characters in either the key or the namespace fields. The key and namespace fields can contain only alphanumeric characters, hyphens, and underscores.

Learn more about the MetafieldDefinition object.

As of GraphQL Admin API version 2022-04, new fields on the App resource are available. These include previouslyInstalled, webhookApiVersion, developerType, requestedAccessScopes, availableAccessScopes, and publicCategory. publicCategory introduces a new enum AppPublicCategory which represents the distribution pattern the app uses.

As of March 14, 2022, app listing pages will include additional details about Partners, such as how many apps they have on the store, the average app rating (for all apps combined), and how long they’ve developed for Shopify. Some of this information is already displayed on the app developer pages, but we’re adding it to the app listing page so that merchants have the decision-making details they need in a single place.

See your app listing page under the Support tab for more details.

As of today, apps will be able to store translation strings in a centralized locales folder accessible across all app blocks and app embeds within a theme app extension.

For more information about the locales directory, refer to the theme app extension framework file structure.

We’ve just released Product Scheduled Publishing to Channels, allowing merchants to schedule products to be published to a sales channel at a specific datetime.

For channels that have product validation workflows, you’ll need to integrate with scheduled product publishing so that your channel can validate products before their scheduled publication datetime.

Complete this form to sign your channel up for scheduled publishing.

For more information, refer to scheduled publishing.

A new attribute (total_duties) is now available on the order object. order.total_duties attribute returns the sum of all duties applied to line items in the order. order.total_duties returns nil if duties are not applicable to the order.

For more information, refer to order.total_duties.

As of February 17th, newly-created themes will generate translatable content keys for content in JSON templates in an altered format. Translations originating outside of JSON templates, such as those stored in the locales/ folder of a theme, are not affected by this change.

Old: section.Template—123456__section_id.block_id.setting_id New: section.product.ext.json.section_id.block_id.setting_id:abc123

We consider the precise format of these keys to be an implementation detail, but try to ensure that the keys remain consistent for a resource over time. Given that, these new keys will only be generated for themes that are uploaded or duplicated after 12:00 EST February 17th.

More information about our translation API is available in our API documentation.

We’ve just released Shopify Markets, which helps merchants sell their products to customers in different countries from a single Shopify store. Merchants can also create unique experiences for their global customers from the Shopify Markets admin's Settings. Apps and themes must use the routes object to support subfolders with locale-aware URLs, and should also use the country object (instead of currency) if they provide storefront switchers.

Shopify Markets is now available for all merchants, with some exceptions. All development stores now have access to Shopify Markets.

For more information, refer to Shopify Markets. Developer considerations for supporting multiple currencies and languages can be found here.

It’s now possible to upsell subscriptions in cart in the online store. We added a new field, selling_plan, to the /cart/change.js endpoint in the AJAX REST API to support adding, updating, and removing the selling plan.

Learn more about supporting subcriptions on shopify.dev.

Apple Pay payments are now accepted for recurring transactions. We added source and virtualLastDigits to the CustomerCreditCard object to support this, in the 2021-10 release.

Note: Available to merchants using Shopify Payments in the US, Canada, Australia, and New Zealand for Visa and Mastercard.

For more information, refer to subscriptions.

In the 2022-04 API version release, Shopify is introducing a Segmentation API for the GraphQL Admin. The API helps app partners support merchants that want to target specific customer groups for marketing, analytics, and reporting. Saved searches and Discount Eligibility based on saved searches, will be deprecated in favor of the Segmentation API.

If your app uses saved searches, then you need to migrate your app to support segments. Learn more about Segmentation in our developer documentation or visit our API forum for questions.

The app that manages connections between Shopify and GitHub has changed its name from Shopify Online Store to Shopify. There’s no change to the app’s existing functionality.

This change reflects earlier updates to Shopify’s GitHub app, which allows it to be used for custom storefront development with Hydrogen, in addition to managing theme code for the online store. We’ll continue to use this app to manage any additional future connections between Shopify and GitHub.

Learn more about the Shopify GitHub integration.

Last year, we announced that there were some updates coming to the Storefront API around object IDs.

As of today, when requesting the unstable, 2022-04 release candidate, or future versions of the Storefront API, the object IDs returned will no longer be Base64 encoded.

Please refer to this migation guide for more details on the change and the steps needed to ensure your apps continue to work properly.

As part of the 2022-04 API release, we've updated the Admin GraphQL and Storefront APIs to provide clearer URLs for the ExternalVideo type:

• The embeddedUrl field has been deprecated in favor of originUrl. Like embeddedUrl, originUrl returns the URL to the video on its hosted platform (either Vimeo or YouTube).
• A new field called embedUrl has been added. It returns the URL required to embed the video inside an iframe.

Learn more about the Admin API ExternalVideo type and the Storefront API ExternalVideo type on Shopify.dev.

We’ve simplified the app model at Shopify by introducing a new experience for creating, configuring, and building custom apps in the Shopify admin.

Custom apps now support all of the functionality that private apps do today, and provide better security. Going forward private apps will be replaced by custom apps, however existing private apps can still be used and modified.

Learn more about the different types of app you can build.

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.

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 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 listed in the Partner Dashboard, on the app's Marketplace extension. The handles are case sensitive. If the string is not in the list 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 fields

source_name (string): The handle indicating the order’s origin. This field is not writable afterwards so make sure to consult the list of handles beforehand. If your handle does not exist in list of, then value will still be saved and will not block order creation.

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

A new checkout experience on Facebook and Instagram is being rolled out to merchants. To ensure your app is compatible for checkout on these marketplaces, update order and fulfillment workflows to capture payments.

As Shopify merchants transition to Shopify Payments for checkout on Facebook and Instagram, orders that were previously processed by Facebook Payments are now transitioning to Shopify Payments as the payment gateway. As a result, how orders are processed will be changing and we are recommending changes to apps to minimize order automation issues arising following the migration.

Learn more about the Updates to Facebook and Instagram order and fulfillment workflows in our developer documentation.

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.

We've made changes to our API License and Terms of Use and our Partner Program Agreement. These changes impact how Shopify Partners and developers interact with the Shopify platform, and offer products or services to merchants.

These changes come into effect as of today, January 5, 2022.

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.

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

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

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

The following customer object properties on the REST Admin API's Order resource are deprecated:

• last_order_id
• last_order_name
• orders_count
• total_spent

These properties will still be available in the Customer resource.

These deprecated properties will be removed from unstable in early 2022. The change will be made official in the 2022-04 REST Admin API version.

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.

At this year's Unite conference, we announced that we wanted to make some sweeping changes and improvements to the Storefront API. Today we're taking another step towards that goal.

The following previously deprecated fields have been removed from the unstable and 2022-04 versions of the Storefront API:

• Article.url
• Blog.url
• Checkout.customer
• Page.url
• Product.presentmentPriceRanges
• ProductVariant.available
• ProductVariant.presentmentPrices
• ProductVariant.presentmentUnitPrices
• ScriptDiscountApplication.description
• Shop.articles
• Shop.blogs
• Shop.collectionByHandle
• Shop.collections
• Shop.currencyCode
• Shop.productByHandle
• Shop.productTags
• Shop.productTypes
• Shop.products
• Shop.shopifyPaymentsAccountId

Additionally, the arguments scale, maxWidth, maxHeight, and crop are no longer available on the following fields:

• Collection.image
• ProductVariant.image
• Product.images
• Article.image

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.

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

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.

Apps that omit the authorization or parent_id parameters when capturing transactions can potentially cause errors for merchants who also use an order editing app.

When creating transactions to capture an authorization, always include either the authorization or parent_id parameter to specify which authorization you'd like to capture. To capture payments successfully, apps must allow for multiple authorization transactions to avoid issues for merchants.

Learn more about using the REST Transaction resource on Shopify.dev.

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.