Developer changelog
Subscribe to the changelog to stay up to date on recent changes to Shopify’s APIs and other developer products, as well as preview upcoming features and beta releases.
Filter by tag:
These are the most recent changes to Shopify’s developer platform.
There are no entries for your filter criteria.
July 01, 2022
Updated contextualPricing to be nullable API
In the 2022-04 API version release, the Product.contextualPricing
and ProductVariant.contextualPricing
fields can now return null
.
This is in preparation for future argument changes. With the current arguments, there is no case where these fields can return null
. However, future arguments will introduce null
cases.
Learn more about contextualPricing
July 01, 2022
Read and write disputes and dispute evidence in the GraphQL and REST Admin API API
You can now read and write disputes and dispute evidence for Shopify Payments using the REST and GraphQL Admin APIs. The following new objects, mutations, and endpoints are available:
GraphQL objects
- DisputeEvidence
- DisputeFileUploadUpdateInput
- DisputeEvidenceFileType
- DisputeFileUpload
GraphQL mutations
- disputeEvidenceUpdate
REST endpoints
- POST /admin/api/2022-07/shopify_payments/disputes/{{dispute_id}}/dispute_file_uploads.json
- DELETE /admin/api/{version}/shopify_payments/disputes/{{dispute_id}}/dispute_file_uploads/{{dispute_file_upload_id}}
- PUT /admin/api/{version}/shopify_payments/disputes/{{dispute_id}}/dispute_evidences.json
For more information, refer to the Dispute resource.
July 01, 2022
Locations now support metafields API
Location resources now support metafields. Use metafields APIs to store additional information in metafield values, like store hours, and then reference them in Liquid.
To learn more about metafields, refer to the metafields documentation. To use location metafields in Liquid, refer to the store_availability Liquid reference.
July 01, 2022
New totalQuantity field on the Storefront API Cart object API
As of GraphQL Storefront API version 2022-07, the Cart
object has a new field: totalQuantity
. This field returns an integer representing the total number of items in the cart.
Learn more about the Cart
object on Shopify.dev.
July 01, 2022
New fields amount and compareAtAmount on the Storefront API CartLineEstimatedCost object API
As of GraphQL Storefront API version 2022-07, the CartLineEstimatedCost
object has two new fields: amount
and compareAtAmount
. Both fields return an object of type MoneyV2
. These new fields allow the price of a product variant on a cart to be queried using buyerIdentity
as the context driver.
Learn more about these fields on Shopify.dev.
July 01, 2022
New Online Store URL redirect object for the Storefront API API
As of GraphQL Storefront API version 2022-07, a new urlRedirects
object has been added.
URL redirects can be used to redirect traffic from one web page to another. The new urlRedirects
object can be used to query the path
and target
URLs for URL redirects already set up on a shop.
Learn more about this object on Shopify.dev.
July 01, 2022
New reason and lineItems fields for rejecting fulfillment requests API
As of GraphQL Storefront API version 2022-07, the fulfillmentOrderRejectFulfillmentRequest
mutation has two new optional arguments:
-
reason
: Identify the reason the fulfillment request was declined. It can be used to filter, group, and provide workflows to help merchants solve rejection issues. -
lineItems
: Identify which line items in a fulfillment request are causing the rejection, and provide a detailed message for each one.
Also in this version, the FulfillmentOrderLineItem
object has a new generic warnings
field, which can be used to display rejection issues for the line item.
July 01, 2022
Action required
The behavior of HasMetafields.metafields has changed API
As of Storefront API version 2022-07, we're deprecating the HasMetafields.metafields
paginated connection in the Storefront API. This connection enabled you to paginate over all visible metafields in a given resource.
HasMetafields.metafields
now accepts a list of metafield namespaces and keys, and returns a list of associated metafields that match the given namespaces and keys.
The updated endpoint is available in unstable, and will be part of the 2022-07 release. The existing paginated behaivor is available in 2022-04 and prior supported stable versions.
For more information, refer to the HasMetafields
interface.
July 01, 2022
Subscription shipping address phone validation API
As of the 2022-07 version of the Admin GraphQL API, the phone
field of the delivery address will be validated on calls to subscriptionContractCreate
and subscriptionDraftUpdate
.
This allows you to ensure phone numbers are properly formatted and will prevent errors that may occur when processing subscription payments with invalid data.
Learn more about SubscriptionContractCreate and subscriptionDraftUpdate on Shopify.dev.
July 01, 2022
Enable Standard metafields by namespace and key API
You can now enable standard metafields on a shop using namespace and key with our GraphQL API.
Learn more about standard metafields.
July 01, 2022
Create delegate access tokens through the GraphQL Admin API API
Avoid sharing an access token across systems with the new delegateAccessTokenCreate
mutation. This mutation creates new tokens with a subset of the total permissions of an app.
For app architectures that require authenticated access from multiple subsystems, it's best to avoid sharing the same token across all systems. Instead, create a new token that has access to only the minimal scopes that are required for proper functioning.
July 01, 2022
Braintree is now available as a CustomerPaymentMethodRemoteInput API
As of API version 2022-07, an input field for Braintree has been added to the CustomerPaymentMethodRemoteInput
object, which is used by the customerPaymentMethodRemoteCreate
mutation. This field can be used to help you migrate Braintree subscription contracts to Shopify.
Learn more about migrating existing subscription contracts to Shopify.
July 01, 2022
Fulfillment service SKU sharing API
The fulfillment service SKU sharing feature gives fulfillment service apps the ability to stock and fulfill product variants together with merchant's locations.
Merchants will be able to stock and fulfill the same variant from multiple fulfillment services. This means that they can now have the same product/variant be stocked at their merchant managed locations as well as 3PL services at the same time.
This feature 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.
When a fulfillment service app sets permits_sku_sharing
to true
, some of the following behaviour will break. If you set a product variant's fulfillmentService
parameter (REST & GraphQL) to manual
, then it no longer means that the variant is stocked only at a merchant-managed location. Apps that use the fulfillmentService
parameter in this way should instead use the location
parameter on the Fulfillment Order resource to determine which location or fulfillment service fulfills a given product variant.
Learn about multi-managed inventory from merchant's perspective.
Learn more about the building a fulfillment service using the fulfillment orders API.
Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.
July 01, 2022
Action required
New WebHooks and App Events for App Usage Spending Limits and Changes to `balanced_used` API
On July 31st 2022 we will be introducing App Usage Spending Limits to provide flexibility for merchants to control the usage charge limit per billing cycle from their Shopify admin. Developers no longer need to set a "one size fits all" app usage capped amount that is difficult to meet a variety of merchants' needs.
Merchants Can Self-Serve Increasing Their Subscription's cappedAmount
As of July 31st 2022 Merchants will be able to increase the cappedAmount
associated with a subscription that has usage pricing. Partners are advised to listen to the app_subscription/update
webhook to stay notified when Merchants update their capped amounts. For instructions on how Merchants will be able to update their cappedAmount
visit the help center
App Usage Webhook Notifications
As of GraphQL Admin API version 2022-07, app developers offering usage-based pricing should subscribe to new webhook updates in advance of the roll out of App Usage Spending Limits. Developers can receive notifications when merchants update their App Spending Limits, which is also the capped_amount
by creating a webhook subscription through the Admin Graphql API to the app_subscriptions/update topic.
Once merchants update their App Spending Limits, developers may need to make updates to their application to allow merchants to incur additional usage charges.
Learn more about Admin Graphql API webhooks here.
Important update about balance_used
endpoint for app usage charges
The balance_used
endpoint in the App Usage Pricing API now shows the running total usage charges for the entire billing cycle. Previously, there was an issue where the usage charge running total, presented on the balance_used
field, resets when a new recurring charge with usage-based pricing is accepted by the merchant. Note that the issue only applied to the value being presented in the balance_used
field and usage charges were not able to exceed the capped_amount
in a cycle.
Going forward, the balance_used
endpoint will always show the total usage charge balance for the billing cycle, which is reflective of what merchants see in the Shopify Admin about their current App Spending Limits.
July 01, 2022
New `Cart.discountAllocations` field and change in `CartLine.discountAllocations` API
As part of the GraphQL Storefront API 2022-07 API release, we are changing how discountAllocations
on Cart
and CartLine
are returned.
-
Cart.discountAllocations
returns discount allocations that are applied to the entireCart
.
CartLine.discountAllocations
now only returns discount allocations that are applied to the specific CartLine
.
CartLine.total
reflects the line total with only line-level discounts applied, not discounts applied to the entire Cart
.
Learn more about the Cart
object on Shopify.dev.
July 01, 2022
Property deprecations in the Admin API Order and LineItem resource API
Multi-managed inventory introduced a breaking change to LineItem resource fulfillment_service
, therefore this field will no longer be supported in REST and GraphQL. Fulfillment services will all be opted into SKU sharing in 2023-04. Please consider using REST FulfillmentOrder#assigned_location & GraphQl FulfillmentOrder#assigned_location
When a fulfillment service app sets permits_sku_sharing
to true, some existing behaviour will break. When a product variant's fulfillmentService parameter (REST & GraphQL) is set to manual, it no longer means that the variant is stocked only at a merchant-managed location. Therefore, apps that use the fulfillmentService parameter in this way should instead use the location parameter on the Fulfillment Order resource to determine which location or fulfillment service fulfills for a given line item.
Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.
Learn more about the building a fulfillment service using the fulfillment orders API.
The following other line item object properties on the REST Admin API's Order resource are deprecated:
origin_location
destination_location
These deprecated properties will be removed from unstable. The change will be made official in the 2022-10 REST Admin API version.
For other recent deprecations on the Orders resource refer to this Change Log
July 01, 2022
Property deprecations in the Admin API ProductVariant resource API
Multi-managed inventory introduced a breaking change to ProductVariant resource fulfillment_service
, therefore this field will no longer be supported in REST and GraphQL. Fulfillment services will all be opted into SKU sharing in 2023-04. Once opted into sku sharing a product variant could be linked to multiple fulfillment services.
For GraphQL to see all associated fulfillment services use InventoryLevelConnection#locations. For REST please refer toInventory levels APIs to see how variants are associated to multiple fulfillment services.
When a fulfillment service app sets permits_sku_sharing
to true, some existing behaviour will break. When a product variant's fulfillmentService parameter (REST & GraphQL) is set to manual, it no longer means that the variant is stocked only at a merchant-managed location. Therefore, apps that use the fulfillmentService parameter in this way should instead use InventoryLevel APIs to determine which location or fulfillment service fulfills a given product variant.
Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.
Learn more about the building a fulfillment service using the fulfillment orders API.
Also the field presentment_prices
is being deprecated in REST and GraphQL. For more context refer to this change log.
July 01, 2022
Release Fulfillment Hold Automation API Changes API
This change adds the public GraphQL fields associated with fulfillment hold automations to the 2022-07 Admin API GraphQL release. Specifically, this adds the following field - MailingAddress.coordinatesValidated
This new boolean field can be used by partners to determine if the coordinates of a mailing address have been validated by Shopify. This unlocks ability to hold fulfillments on unvalidated mailing address and ensure that merchants check prior to requesting fulfillments from their 3PL.
Learn more about holding fulfillments with GraphQL and with REST Learn more about Shopify Flow
July 01, 2022
Legacy Fulfillment API Deprecation API
The Fulfillment API is being deprecated in the Shopify 2022-07 release. Apps will have until the 2023-01 release to start using Fulfillment Orders. To help you seamlessly migrate, we’ve crafted a migration guide that walks you through the process of moving to Fulfillment Orders.
July 01, 2022
GraphQL schemas will use the "@deprecated" directive for input fields and arguments API
As of API version 2022-07 all GraphQL schemas will start using the "@deprecated" directive for input fields and arguments which have been deprecated. API versions 2022-04 and below will continue to use the description for deprecation warnings.
It is recommended you use a GraphQL client which supports deprecated input fields and arguments when using GraphQL API versions 2022-07 and above. For example graphql-js added support as of version v15.5.0. See the official GraphQL spec for more details.
July 01, 2022
New PredictedSpendTier field on the Customer object API
As of GraphQL Admin API version 2022-07, a new statistics
field has been added to the Customer
object for computed customer statistics. It includes a new field predictedSpendTier
which indicates the predicted spend of a customer with a shop.
For more information, refer to the CustomerStatistics
field in the GraphQL Admin API reference.
July 01, 2022
Updated requirements for protected customer data API
Starting with API version 2022-10, we’re introducing updated requirements for apps that use customer data. Updated requirements will be published prior to the release of API version 2022-10.
The protected customer data requirements focus on data minimization, transparency, and security so that Partners can better support merchants' paths towards compliance with privacy and data protection rules.
Learn more about how you can be ready for protected customer data.
June 28, 2022
Introducing Checkout Extensibility Tools
With Checkout Extensibility, you can now build apps to customize checkout and Shop Pay. You can leverage Checkout UI extensions and Shopify Functions to surface new functionality, Checkout Branding API to customize styling, and Pixels to track events.
Checkout Extensibility is now available in developer preview.
Learn more about Checkout Extensibility on Shopify.dev.
June 27, 2022
Apply multiple discounts to an order with discount combinations API
As of GraphQL Admin API version 2022-07, you can use the Discount APIs to modify combination settings on a discount. This allows a customer to apply more than one discount to their order.
Discount combinations are available now as part of the Checkout extensibility developer preview.
Learn more about how discount combinations work.
June 22, 2022
New type field on Storefront API CartCustomDiscountAllocation object API
As of GraphQL Storefront API version 2022-10, CartCustomDiscountAllocation
object has a new field: type
. This field returns the type of custom discount (i.e. manual or script) on a discount allocation from a cart line.
Learn more about the Cart
object on Shopify.dev.
June 22, 2022
Introducing Shopify Functions Tools
Shopify Functions lets you extend or replace key parts of Shopify’s backend with custom logic. Functions run on Shopify infrastructure, making them both scalable and performant.
Functions are now available in developer preview for product, order, and shipping discounts.
Learn more about Shopify Functions on Shopify.dev.
June 22, 2022
Embedded App Improvements with App Bridge Tools
With the latest App Bridge enhancements, your app will now look, feel, and perform like it’s a part of Shopify.
More specifically, App Bridge mobile apps can now load 85% faster from the Shopify iOS and Android apps when you enable mobile optimization for your embedded app. App Bridge apps can also now leverage full-screen mode, just like our first-party apps, for complex workflows in the Shopify admin. Lastly, apps that use the NavigationMenu component will now have their navigation embedded into the Shopify admin for faster, more natural access.
Learn more about App Bridge on Shopify.dev.
June 22, 2022
Introducing Shopify CLI 3.0 Tools
The updated Shopify CLI 3.0 is both easier to use and more powerful than ever. With Shopify CLI 3.0, we’ve simplified the development process by reducing the number of commands that you need to get started from 13 to 5.
You can also now leverage a single project for your app and extensions, preview your entire project with one command, and push your entire project together with a single command when you’re finished.
June 21, 2022
Selling Plan API now supports pre-orders and try before you buy API
As of GraphQL Admin API version 2022-07, we have expanded the Selling Plan API enabling you to integrate support for new deferred purchase options like pre-orders and try before you buy into the Shopify Checkout.
June 21, 2022
New API for collecting deferred payments on orders API
As of GraphQL Admin API version 2022-07, we have introduced new APIs that enable you to collect deferred payment on an order using a vaulted card belonging to the customer. The orderCreateMandatePayment mutation will be available for charging payments against a vaulted credit card. This API returns a GraphApi::Job and paymentReferenceId. This paymentReferenceId can be used to poll the status of the payment using the orderPaymentStatus query.
June 21, 2022
App distribution decoupled from app creation, new Partner Dashboard navigation Platform
What a relief - app distribution is now decoupled from the app creation flow in the Partner Dashboard! This means you no longer have to select a public or custom app type before you start coding.
We’ve also improved the navigation within the Partner Dashboard and added a Distribution page, where can manage your Shopify App Store listing or generate your merchant install link. Also, if you’re building your app using Shopify CLI, you’ll be able to copy and paste the commands you need to get started right from the dashboard.
Learn more about app distribution and selecting a distribution method.
June 17, 2022
Selling plans can now specify a fixed cutoff day for a delivery policy API
As of GraphQL Admin API version 2022-07, the SellingPlanAnchorInput
type has an additional optional field.
cutoff_day
represents a fixed cutoff day for each anchor, to be used for monthly and weekly selling plans. Use this method if the cutoff should land on the same day each month.
You can also specify a cutoff using the cutoff
field of the SellingPlanRecurringDeliveryPolicyInput type, which represents a duration. Using cutoff
, the exact cutoff day could be different based on the number of days in the month.
June 15, 2022
Changes to Cart and CartLine on Storefront API API
As part of the GraphQL Storefront API 2022-07 API release, the following are changes to have been made to the Cart
and CartLine
object:
- New
attribute
field with akey
argument -
estimatedCost
is renamed tocost
onCart
. -
estimatedCost
is renamed tocost
onCartLine
. - Add
subtotalAmountEstimated
,totalAmountEstimated
,totalTaxAmountEstimated
,totalDutyAmountEstimated
toCartCost
-
amount
is renamed toamountPerQuantity
onCartLineCost
. -
compareAtAmount
is renamed tocompareAtAmountPerQuantity
onCartLineCost
.
Learn more about the Cart
object on Shopify.dev.
June 13, 2022
New options for app subscription upgrades and downgrades API
As of GraphQL Admin API version 2022-07, app developers can now choose their preferred update behavior when upgrading or downgrading merchant application subscriptions.
By specifying the desired AppSubscriptionReplacementBehavior
type, app developers can control whether the new subscription goes into effect immediately or is deferred to the end of the current subscription's billing cycle. By default, all app subscription changes will continue with the existing behavior.
Learn more about specifying app subscription replacement behavior on Shopify.dev.
June 07, 2022
Action required
Removal of Deprecated Storefront API Checkout Mutations API
In the 2022-01
Storefront API release we removed several deprecated fields. With the 2022-07
release, we're continuing with that effort and removing the following deprecated checkout mutations:
checkoutGiftCardApply
checkoutGiftCardRemove
checkoutEmailUpdate
checkoutDiscountCodeApply
checkoutCustomerAssociate
checkoutCustomerDisassociate
checkoutCompleteWithTokenizedPayment
checkoutCompleteWithTokenizedPaymentV2
-
checkoutShippingAddressUpdate
checkoutCompleteWithCreditCard
checkoutAttributesUpdate
These mutations will continue to be available within the 2022-04
API version until it's sunset in April 2023. For more information on Shopify API versioning, refer to our documentation.
June 07, 2022
Shopify CLI: Preview your theme changes using any theme Tools
When developing a theme using Shopify CLI, you can now preview your local changes using any theme in a store. To specify a theme, run the Shopify CLI theme serve
command with the new -t
or --theme
flag:
shopify theme serve -t my-unpublished-theme
Previously, developers could only preview changes using development themes.
Caution:
Before running shopify theme serve
, pull your remote theme to ensure that any recent changes don't get overwritten by your local development files.
Learn more about previewing your theme using Shopify CLI.
June 01, 2022
Action required
Support for the XML response format is deprecated from the Admin REST API API
Starting in version 2022-07, support for the XML response format and XML payloads in the Admin REST API is removed. Requests expecting an XML response will result in a 404. Requests that send an XML payload will result in a 415.
May 09, 2022
GraphQL Admin API now supports custom content by market API
As of May 9, 2022, you can use the GraphQL Admin API unstable
version to surface custom content to buyers in a specific market, including custom content for a store’s default language.
This feature enables merchants to provide the following kinds of localized and custom content:
- Support showing regional spelling or preferred terms. For example, a “Sweaters” menu title for a United States market, and a “Jumpers” menu title for a United Kingdom market.
- Display promotional content based on the buyer’s market. For example, a custom Thanksgiving announcement bar in October for Canadian buyers.
For more information, refer to examples in our developer documentation for the translationsRegister, translationsRemove, and translatableResource mutations.
May 03, 2022
Support added for compressed GIF images Platform
A much wider range of optimized GIFs, including LZW compression, are now accepted for upload.
To learn more about which image formats Shopify accepts refer to: https://help.shopify.com/en/manual/online-store/images/theme-images#image-formats
April 22, 2022
Subscription apps support Google Pay API
Google Pay payments are now accepted for recurring transactions. For these transactions, the CustomerCreditCard
will have a source of google_pay
.
For more information, refer to Building subscription apps.
April 19, 2022
TranslationsRemove endpoint now supports removing asset translation keys API
The TranslationsRemove
endpoint now supports deleting translations that are stored in asset files.
Learn more about the TranslationsRemove
endpoint.
April 19, 2022
Themes now support 25 sections per template and 50 blocks per section Platform
Based on your feedback, we've updated the number of sections and blocks you can add within a template. You can now add up to 25 sections per template and 50 blocks per section within each template.
This will support use cases like: * Adding more blocks to an FAQ section * Adding multiple profile sections on the About Us page * Creating multiple areas of focus on the homepage * Section and block support for very large collections
You can specify a lower limit with the max_blocks
attribute.
Learn more about section and block limits in our theme architecture documentation.
April 04, 2022
Theme app extensions now support conditional app blocks API
The visibility of an app block, or app embed block, of a theme app extension can now be controlled based on a custom condition.
The condition can be included in the block's schema with the available_if
attribute, and the state of the condition is stored in an app-owned metafield. The metafield can be accessed through the Liquid app
object.
To learn more about conditional app blocks, refer to Theme app extensions framework.
April 04, 2022
New app Liquid object API
A new Liquid app
object is available for use within the context of theme app extensions and app proxies. The app
object can be used to access an app's metafields.
Refer to the app
object documentation for more information.
April 04, 2022
New checkoutChargeAmount field added to Cart object on Storefront API API
As of GraphQL Storefront API version 2022-04, a new checkoutChargeAmount
field has been added to Cart
. It indicates the subtotal amount to be paid for this cart at checkout, not including any deferred payments. This field is currently restricted behind the extend_selling_plans_api
beta flag.
The checkoutChargeAmount
field is similar to the subtotal
field. The subtotal
field indicates the subtotal that will be paid altogether, including any payments that will be made at a later date. The checkoutChargeAmount
is the actual price that will be paid at the time of checkout.
April 01, 2022
New value for the DigitalWallet enum API
As of API version 2022-04, the DigitalWallet
enum has a new value, FACEBOOK_PAY
. This change affects both GraphQL Admin and Storefront APIs.
For more information, refer to the DigitalWallet
enum in the GraphQL Admin API reference or Storefront API reference.
April 01, 2022
New enum value for CustomerPaymentMethodRevocationReason API
As of GraphQL Admin API version 2022-04, the CustomerPaymentMethodRevocationReason object has a new enum value: MERGED. This value is assigned when a customer replaces one payment method with another existing payment method, leaving this revoked payment method with no associated subscription contracts.
Learn more about this API on Shopify.dev.
April 01, 2022
New field originTime for subscriptionBillingAttempt API
As of GraphQL Admin API version 2022-04, a new originTime
field has been added to subscriptionBillingAttempt
. Fulfilment intervals for subscriptions are normally calculated using the billing attempt date, but may be overridden with this new field if the billing happens to occur after the current anchor date. This can be done to prevent fulfilment from being pushed to the next anchor date when billing is delayed.
Visit our documentation on Creating a Billing Attempt and Advanced Delivey Behaviours for Subscriptions to learn more about this new field.
April 01, 2022
New fields for custom attributes added to subscription contracts API
As of the 2022-04 version of the Admin GraphQL API, the customAttributes
field will be present on the SubscriptionContract
, SubscriptionDraft
, and SubscriptionDraftIndex
objects. Those new fields correspond to the existing field of the same name on the Order
object.
This allows you to update a subscription contract draft with new custom attributes. Those attributes will be copied over to new orders created from that subscription contract.
Learn more about SubscriptionContract
and subscriptionDraftUpdate
on Shopify.dev.
April 01, 2022
New SEO field on the Storefront API Collection object API
As of GraphQL Storefront API version 2022-07, the Collection
object has a new field: SEO
. This field returns an SEO
object.
Learn more about this API on Shopify.dev.
April 01, 2022
Action required
New pending mutation in Payments Apps API 2022-04 release API
In the 2022-04
release of the Payments Apps GraphQL API, we're introducing a way to mark payments as pending. To support this, a new mutation can be used in cases where a payment cannot be completed quickly.
New pending mutation
The pending payments feature is now officially available for payments apps. You can mark a payment as pending if the payment can't be completed within a reasonable amount of time. This means buyers won't need to wait for slow transactions to finish before their order is completed. Learn more about pending a payment on Shopify.dev.
Updated pending behaviour in the Admin
While the payment is pending, the actions a merchant can take on the order will be restricted so as to not interfere with the payment that is pending. These restrictions are lifted as soon as the payment is completed or expires. A pending payment will expire if you fail to complete the payment within a reasonable time. Learn more about pending payments in the Shopify Help Center.
Status field deprecation
The status
field on payment, refund, capture, and void session objects is deprecated and replaced by the state
field introduced in the 2022-04 API release. Pending payments are not supported by the status
field and will raise an error.
April 01, 2022
New field deliveryGroups for the cart object API
As of GraphQL Admin API version 2022-04, a new deliveryGroups
connection has been added to cart
. It consists of a group of delivery options available for the line items in the cart, for a specified shipping address. Delivery groups are only available for logged-in customers with a full default address.
Refer to our documentation on cartCreate and customerCreate to learn more about how to create a cart associated with a logged-in customer.
April 01, 2022
Attribute orders to a sales channel API
As of Admin API version 2022-04, two new fields, source_url
and source_identifier
have been added to the Orders and Checkout objects in both the REST and Graph APIs. The source_name
field will also be updated across these APIs for the Orders, Draft Orders and Checkout object. By adding a valid source_name
, the order will be attributed to a list of sales channels found within the partner's dashboard.
More information can be found here
April 01, 2022
Storefront API @inContext directive supports languages API
As of version 2022-04, the @inContext
directive in the Storefront API accepts a language
argument in addition to country
. If the requested language is active for the given country, as configured within the shop's Market settings, then the query will return translated values.
The list of available languages can be accessed with this query:
query Localization @inContext(country: CA, language: FR) {
localization {
# for the current country
availableLanguages {
isoCode
endonymName
}
# and for non-current countries
availableCountries {
isoCode
name
availableLanguages {
isoCode
endonymName
}
}
}
}
If an unsupported language or country is requested via @inContext
, the response will fall back to supported values. In all cases, the actual country and language context will be returned as a response extension.
{
"data": {
"productByHandle": {
"title": "Cat bed",
"variants": {
"edges": [
{
"node": {
"priceV2": {
"amount": "100.0",
"currencyCode": "CAD"
}
}
}
]
}
}
},
"extensions": {
"context": {
"country": "CA",
"language": "EN"
}
}
}
Learn more about supporting multiple languages on storefronts.
April 01, 2022
New value for the FilterType enum API
As of API version 2022-04, the GraphQL Admin API's FilterType
enum has a new value(BOOLEAN
). The BOOLEAN
value is assigned when a filter is based off a boolean
type metafield definition.
For more information, refer to the Filter
object.
April 01, 2022
New menu field in the Storefront API API
As of the 2022-04 version of the Storefront API, you can fetch a navigation menu by handle with the menu
field. The new field returns a Menu
object, and can be used to replicate a merchant's Online Store menus on custom storefronts.
April 01, 2022
Deprecated fields on the Customer object API
The following are changes to the GraphQL Admin API's Customer
object:
- The
orders_count
field is renamed tonumber_of_orders
. - The
total_spent
andtotal_spent_v2
fields are replaced byamount_spent
. - The
has_note
field is removed. Thenote
field still exists on thecustomer
. - The
has_timeline_comment
field is removed. To query for comments on the timeline, use the events connection and aquery
argument containingverb:comment
, or look for aCommentEvent
in the__typename
of events.
For more information, refer to the Customer
object.
April 01, 2022
New email marketing consent for customers and deprecated fields API
The accepts marketing and related fields were used to indicate if a customer subscribed to all marketing channels. In 2021, we started separating marketing consent into SMS and email channels by introducing SMS marketing consent.
In API version 2022-04, we’re completing that split by deprecating the accepts marketing fields and replacing them with email marketing consent fields. You’ll need to update your apps to use the SMS and email marketing consent fields to send the opt-in level, consent state and the time at which the consent was granted, instead of a simple Boolean to express the marketing consent of customers.
As of GraphQL Admin API version 2022-04, we're deprecating the acceptsMarketing
, acceptsMarketingUpdatedAt
and marketingOptInLevel
fields on the Customer
object and CustomerInput
input object.
The deprecated fields are replaced by the following new fields, that you can access using the emailMarketingConsent
field on the CustomerInput
object:
marketingState
consentUpdatedAt
marketingOptInLevel
For more information, refer to the CustomerInput
input object on Shopify.dev.
As of REST Admin API version 2022-04, we're deprecating the accepts_marketing
, accepts_marketing_updated_at
and marketing_opt_in_level
fields on the Customer
resource.
The deprecated fields are replaced by the following properties on the new email_marketing_consent
field for the Customer
resource:
state
consent_updated_at
opt_in_level
For more information, refer to the Customer
resource on Shopify.dev.
April 01, 2022
New checkoutCharge field added to the Storefront API sellingPlan object API
As of GraphQL Admin API version 2022-04, a new checkoutCharge
field has been added to sellingPlan
. It consists of a charge type (either percentage
or price
), and an amount, indicating how much of the product's cost will be charged at the time of checkout. This field is currently restricted behind the extend_selling_plans_api
beta flag.
April 01, 2022
New: Markets API API
After the release of Shopify Markets, we are following up with the Markets API in version 2022-04. The API allows you to create, update, and delete markets and their settings.
Shopify Markets unlocks the ability to create high-performing, localized buyer experiences by allowing merchants to specify the domain, language, currency and price that international buyers see when browsing a merchant's storefront.
You can learn more about the Markets API on shopify.dev.
April 01, 2022
New fulfillment information API fields for fulfill by and expected delivery time API
GraphQL Admin API
As of GraphQL Admin API version 2022-04, we're adding the fulfillBy
to the FulfillmentOrder
object. The field represents the latest date and time when all items in the fulfillment order need to be fulfilled.
We're also adding the maxDeliveryDateTime
and minDeliveryDateTime
fields to the DeliveryMethod
object. When combined, they represent a range of time when the delivery is expected to be completed.
Learn more about FulfillmentOrder
and DeliveryMethod
objects.
REST Admin API
As of REST Admin API version 2022-04, the following properties are added to the FulfillmentOrder
resource:
fulfill_by
-
delivery_method.max_delivery_date_time
-
delivery_method.min_delivery_date_time
Learn more about the FulfillmentOrder
resource.
April 01, 2022
Enhancements to pagination for GraphQL connections API
In addition to edges
, GraphQL connections now have a nodes
field. When you only query node
on edges
, you can simplify the query.
For example:
{ connection { edges { node { fields } } }
can be simplified to:
{ connection { nodes { fields } } }
PageInfo
has been expanded as well to include startCursor
and endCursor
.
When these fields are used in tandem, it can simplify the shape of return data for pagination.
Previous query format:
{ connection { edges { cursor node { fields } } pageInfo { hasNextPage } } }
Improved query format:
{ connection { nodes { fields } pageInfo { hasNextPage endCursor } } }
April 01, 2022
New app billing discounts and app trial extensions Shopify App Store
We are introducing new flexible ways for app partners to offer merchants incentives for app subscriptions.
Recurring App Discounts
As of GraphQL Admin API version 2022-04, app developers can now offer limited time discounts on recurring app charges through the Billing API. Partners may define a percentage or fixed amount discount that will be applied to a designated number of billing cycles (e.g. 20% of 6 billing cycles). This will enable app partners to create introductory offers for new merchants.
Learn more about app billing discounts on Shopify.dev.
App Trial Extensions
App developers can increase the number of trial days offered to a recurring app charge by using the new appSubscriptionTrialExtend offered without merchants accepting a new app subscription. This will enable developers to provide new merchants additional time to trial products. App trial extension is currently available in the unstable version of the GraphQL Admin API.
Learn more about trial extensions on Shopify.dev.
April 01, 2022
Providing app credits in the appSubscriptionCancel mutation API
As of GraphQL Admin API version 2022-04, app partners can issue prorated credits for the unused portion of the app subscription when a recurring app charge is cancelled. This enables developers to automatically provide app credits to merchants when they uninstall an app or cancel a subscription, and reduce support requests to app partners for refund requests.
For more information, refer to the appSubscriptionCancel mutation.
April 01, 2022
new checkoutChargeAmount and remainingBalanceChargeAmount fields on Storefront API API
As of GraphQL Admin API version 2022-04, checkoutChargeAmount
and remainingBalanceChargeAmount
fields have been added to sellingPlanAllocation
. These fields indicate how much of a product variant's price must be paid upfront, and how much must be paid at a later date. This field is currently restricted behind the extend_selling_plans_api
beta flag.
April 01, 2022
Videos in Files and Metafields API
You can now create videos and transcode them to multiple formats, using the FileCreate mutation.
You can also attach videos to metafields using file_reference. These videos are also available using the Storefront API.
April 01, 2022
Action required
Deprecating countries field on PriceListContextRuleInput API
With the launch of the Markets API as of version 2022-04, price lists are no longer associated with a country, but with a market. We've deprecated the countries
field on the PriceListContextRuleInput
object and replaced it with a new field called marketId
.
For more information, refer to the PriceListContextRuleInput
object.
April 01, 2022
App-owned Metafields API
As of GraphQL Admin API version 2022-04, a new owner type ApiPermission
is now available for metafields. A metafield with this permission type will only be readable and writable by the app that owns the metafield.
March 31, 2022
Updates to error codes for translationsRegister API
Although the INVALID_LOCALE_FOR_SHOP
error code was introduced in the 2020-07 version, it has never been used to represent a locale
field related error when calling the translationsRegister
mutation.
As of GraphQL Admin API version 2022-04, the INVALID_LOCALE_FOR_SHOP
error code is used to represent all errors related to the locale field
on the Translation
object.
Previous verions will still use the INVALID_CODE
error code to represent errors related to the locale field.
March 31, 2022
Online Store 2.0: Two-way sync support on Shopify CLI Tools
Theme developers can now use the Shopify CLI theme serve
command with the new --theme-editor-sync
flag. When active, theme editor changes are automatically synced back to the local development files.
Learn more about Shopify CLI theme commands.
March 24, 2022
CI/CD support for scripts, extensions Tools
Developers can now programmatically push their scripts and extensions to Shopify from their CI/CD pipelines with CLI authentication tokens.
For more information on how to set up CI/CD for your scripts and extensions, visit our developer documentation.
March 23, 2022
New theme editor setting types: product list and collection list Themes
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.
March 21, 2022
Changes to metafield definition error codes API
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.
March 15, 2022
New fields on App and AccessScope API
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.
March 14, 2022
App store listings now have additional Partner details Shopify App Store
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.
March 03, 2022
Theme app extensions now support locales directory API
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.
February 24, 2022
Scheduled Publishing to Channels is now Generally Available API
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.
February 18, 2022
Display duties with Liquid using `order.total_duties` Themes
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.
February 17, 2022
Changes to Theme Translatable Content Keys API
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.
February 15, 2022
Shopify Markets is now Generally Available Platform
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.
February 14, 2022
Cart change REST API now supports changing selling plan API
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.
February 03, 2022
Subscriptions APIs now support Apple Pay API
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.
February 01, 2022
Action required
Segmentation API available in 2022-04 release API
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.
January 31, 2022
Name change for Shopify’s GitHub app Tools
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.
January 27, 2022
Action required
Changes to Storefront API Object IDs API
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]https://shopify.dev/custom-storefronts/migration/object-ids) for more details on the change and the steps needed to ensure your apps continue to work properly.
January 26, 2022
Updated Admin GraphQL/Storefront ExternalVideo URL fields API
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 oforiginUrl
. LikeembeddedUrl
,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.
January 24, 2022
Introducing a new custom app developer experience Platform
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.
January 21, 2022
Channel Attribution is now available in beta API
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")
January 19, 2022
Action required
Updates to Facebook and Instagram Order and Fulfillment Workflows API
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.
January 17, 2022
Stripe as additional payment gateway for subscriptions Platform
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.
January 05, 2022
Action required
Updates to our API License and Terms & Partner Program Agreement Platform
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.
January 05, 2022
New Regulatory operating fee field in the Partner payout and app earnings CSV Shopify App Store
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.
January 04, 2022
Authorization errors in mutations are refined API
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.
January 01, 2022
Introducing standardized and custom product types to GraphQL Admin API API
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.
January 01, 2022
New field on the SuggestedOrderTransaction object API
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.
January 01, 2022
New sellable online quantity field on ProductVariant object API
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.
January 01, 2022
New barcode field on the Storefront API ProductVariant object API
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.
January 01, 2022
New subscriptionPolicy field on Shop object API
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.
January 01, 2022
New mutation OrderInvoiceSend API
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.
January 01, 2022
New error codes for bulkOperationRunMutation API
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.
January 01, 2022
Metafield Definitions available on Order, Collection, and Customer API
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.
December 21, 2021
Action required
Property deprecations in the REST Admin API Order resource API
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.
December 17, 2021
New endpoint: translatableResourcesByIds API
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.
December 16, 2021
Developer preview: Shopify Markets Platform
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.
December 15, 2021
Subscription support on dynamic and accelerated checkout methods for PayPal Express API
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.
December 10, 2021
Locale fields are now appended with language and country codes API
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.
December 10, 2021
Action required
Cleaning up deprecations in the Storefront API API
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 upcoming 2022-01
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
December 09, 2021
Adding the manually_revoked value to theCustomerPaymentMethodRevocationReason enum API
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.
December 07, 2021
JSON templates now have limit of 1000 per theme Themes
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.
December 06, 2021
Contract notes for subscriptions API
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.
December 03, 2021
Adding mediaWarnings and 3D model bounding box information API
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.
December 03, 2021
Adding new enum value for handling processing errors for Model3d objects API
[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.
November 25, 2021
Action required
Updating apps capturing transactions API
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.
November 19, 2021
Changes to Cart default bundled section rendering (Ajax API) API
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.
November 16, 2021
Make images responsive with the new image_tag filter Themes
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.
November 16, 2021
Vulnerable password validation on the Storefront API's Customer object API
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.
November 10, 2021
New: Marketplace Kit API
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
November 04, 2021
Specify private metafields for webhooks using GraphQL Admin API API
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.
October 29, 2021
Updated permissions on the Shopify Online Store app for GitHub Tools
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.
October 28, 2021
Expose selected fields on AbandonedCheckout GraphQL API to public API
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
.
October 27, 2021
Storefront filtering now supports filters on product and variant metafields Themes
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.
October 22, 2021
Subscriptions APIs now support Shop Pay API
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.
October 01, 2021
New: Payment Terms API API
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.
October 01, 2021
New webhook to notify when a billing attempt is 3DS-challenged API
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.
October 01, 2021
Action required
Removed 'full' permission on User resource API
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.
October 01, 2021
Bulk product resource feedback API now available API
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
October 01, 2021
Origin address property in the REST Fulfillment resource API
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.
October 01, 2021
Action required
Improvements and changes coming to the Storefront API API
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.
October 01, 2021
New fields in TranslatableResourceType enum API
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.
October 01, 2021
New field on the CustomerPaymentMethod object API
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.
October 01, 2021
New field on the Order object API
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.
October 01, 2021
New property on Fulillment.line_item object API
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.
October 01, 2021
New webhook topic notifies when a Bulk Operation has finished API
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.
October 01, 2021
New type field for the BulkOperation GraphQL object API
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.
October 01, 2021
customerPaymentMethodGetUpdateUrl mutation for Customer payment methods is now available API
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.
October 01, 2021
Contextual pricing for products is now available in the GraphQL Admin API API
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.
September 29, 2021
Preload key resources with the preload_tag filter Themes
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.
September 29, 2021
New Stripe PaymentTokenType for Storefront API API
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.
September 28, 2021
Checkout URL query parameters no longer contain customer details Platform
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.
September 24, 2021
New form to report violations of Shopify's Partner Program Agreement Platform
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
September 22, 2021
SMS marketing consent API
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.
September 20, 2021
Subscription offers for post-purchase is now available API
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.
September 20, 2021
Fulfillment Order has a new fulfill_by field API
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
.
September 17, 2021
New fields on the GraphQL Admin API's Shop object API
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.
September 17, 2021
Increasing the app block limit from 10 to 25 for theme app extensions API
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.
September 15, 2021
Updates to our Partner Program Agreement effective September, 15 2021 Platform
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.
September 14, 2021
Developer preview: Fulfillment service SKU sharing API
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.
September 07, 2021
Theme app extension requirement - all new apps Shopify App Store
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.
August 31, 2021
Liquid support now available for Predictive Search API API
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.
August 18, 2021
New currency formatting theme setting guidelines Themes
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.
August 17, 2021
Action required
Removing the @global block type in favour of the @app block type in theme sections Themes
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.
August 17, 2021
New metafield type: Rating API
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.
August 12, 2021
Shopify now serves minified JavaScript files automatically Platform
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.
August 12, 2021
New webhook topics for SellingPlanGroups API
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.
August 01, 2021
Changes to the Partner payout CSV and app earnings CSV Platform
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 theProcessing fee
as well as theShopify 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.
August 01, 2021
New updates to Partner API API
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
, andAppUsageSale
have a new field titledprocessingFee
. TheprocessingFee
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 ofprocessingFee
amount from your app charge and adjustment to a merchant. -
SALE_SHOPIFY_FEE
in the TaxTransactionType enum is deprecated and replaced by theSALE_FEES
value. When taxes are charged on all fees for an app, theme, or service transaction, theSALE_FEES
value is returned in theTaxTransaction
object. - The
type
field inTaxTransaction
object is deprecated. A new field titledtaxType
is now present on the object, which will return eitherTaxTransactionType.REFERRAL_COMMISSION
for taxes paid out on your commission fee for a referral orTaxTransactionType.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.
August 01, 2021
Published app developers can register for the new revenue share model on August 1st Shopify App Store
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.
August 01, 2021
Updates to our Partner Program Agreement now in effect Platform
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.
July 15, 2021
Manage webhooks with Google Cloud Pub/Sub API
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.
July 13, 2021
Action required
Validate draft versions of theme app extensions using Theme Check Tools
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.