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.
RSS updatesThere are no entries for your filter criteria.
November 01, 2024
GraphQL Over HTTP API
The handling of GraphQL requests via HTTP will evolve slightly as of 2025-01
API versions in accordance with the GraphQL over HTTP spec. These changes refine how a request's Content-Type
and Accept
headers work, and offer additional granularity in response status codes.
New response format
A new application/graphql-response+json
response format is available. Requests may select this format using the Accept
header, for example:
Accept: application/graphql-response+json, application/json
The above favors receiving a application/graphql-response+json
response by listing it first. This new format is the same as JSON aside from its status codes:
200 OK
- For
application/graphql-response+json
, this status indicates that the JSON payload was valid and that the submitted GraphQL document attempted execution on the server. Note that the response payload may still contain errors encountered during execution along with partial data. - For
application/json
, this status only indicates that the JSON payload was valid.
400 Bad Request
- For
application/graphql-response+json
, this status indicates that the JSON payload was invalid, or that the submitted GraphQL parameters failed static validation and were not executed. - For
application/json
, this status only indicates that the JSON payload was invalid.
Usage summary
For requests to 2025-01
versions and after:
- Use the
/graphql
endpoint. Using/graphql.json
will automatically respond withapplication/json
as it does now. - The request body must contain a spec JSON encoding.
- The
Content-Type
header must specifyapplication/json
. The legacyapplication/graphql
request format is no longer supported. Requests with no supported content type will receive a415 Unsupported Media Type
response. - The
Accept
header now supportsapplication/graphql-response+json
and/orapplication/json
response formats. Requests with no supported accept types will receive a406 Not Acceptable
response. - Accepting
*/*
will default to aapplication/graphql-response+json
response.
These changes do NOT affect unstable
versions at this time, or Storefront API. A breaking change announcement with migration timeline will be announced prior to any unstable transition.
November 01, 2024
Action required
Content type application/graphql
is deprecated
API
The Content-Type: application/graphql
request format is deprecated and will no longer be accepted as of 2025-01 schema versions. As of 2025-01
schemas, all requests must specify Content-Type: application/json
and post a spec encoded body. See GraphQL Over HTTP update for more details.
November 01, 2024
Action required
Removing multiLocation
field from ShopFeatures
API
As of the 2025-01 release of the Admin GraphQL API, the deprecated multiLocation
field on ShopFeatures will be removed.
Use the locationsCount query to determine how many locations a shop has.
October 28, 2024
Web pixels now support checkout error events API
We’re rolling out new standard events to web pixels that enable you to better understand the issues that buyers encounter in checkout. Merchants can now capture specific alerts seen by buyers, such as inline field validations and page-level alerts, and errors from Checkout UI Extensions. Any pixels subscribing to all standard events will automatically receive these new types.
Learn more about the new events here.
October 24, 2024
Action required
Update to fulfillmentHold.heldByApp
field from fulfillmentHold.heldBy
field
API
As of the 2025-01
API version, the heldBy
string field on the fulfillmentHold
GraphQL object will be replaced by the newly introduced heldByApp
object field.
This new field provides access to all attributes of the App object, unlike the deprecated heldBy
field, which only indicated the app's title.
If you currently query fulfillmentHold.heldBy
, you should transition to querying fulfillmentHold.heldByApp.title
.
October 21, 2024
Limit for full-page extensions in customer accounts API
A full-page extension target (customer-account.page.render
or customer-account.order.page.render
) can no longer coexist with any other targets in the same extension. This change improves performance and provides a better merchant experience in the checkout and accounts editor. If your full-page extension is best used with other extensions in your app, create an editor extension collection to encourage merchants to add all the extensions in the collection.
This change will only impact the deployment of new extensions or new versions of existing extensions. Existing extensions will not be affected until a new version is deployed.
October 16, 2024
Storefront API Cart now supports removing Gift Cards API
As of version 2025-01 of the GraphQL Storefront API, Cart now supports removing Gift Cards by Id.
After a cart has been created and a Gift Card applied - perform the cartGiftCardCodesRemove
mutation to remove one or more gift cards.
October 14, 2024
API StringConnection
includes nodes
field
API
As of API version 2025-01
, you can access StringConnection.nodes
field shorthand to retrieve an array of strings directly instead of via edges
. This connection type is now consistent with other connection types in the schema.
Learn more about StringConnection
on GraphQL Admin API and Storefront API.
October 11, 2024
Checkout UI extensions - Extensions in the reductions render before/after targets will now render in the header order summary on 1 page mobile checkouts API
As of October 11, 2024, checkout UI extensions targeting the purchase.checkout.reductions.render-before
and purchase.checkout.reductions.render-after
extension targets will now render in the order summary at the top of the page for one page mobile checkouts. Previously, extensions in these targets would only appear in the order summary at the bottom of the page. This will apply to checkout UI extensions on all API versions.
For more details, please follow up in the github issue in our public repo
October 10, 2024
Shopify Payments Payout Summary GraphQL surfaces advance fees and advance gross fields API
As of GraphQL Admin API version 2024-10, ShopifyPaymentsPayoutSummary now surfaces ADVANCE_FEES
and ADVANCE_GROSS
fields.
Learn more about ShopifyPaymentsPayoutSummary
on Shopify.dev.
October 07, 2024
lineItem
connection is no longer deprecated on FulfillmentOrderLineItem
resource
API
As of today, you can use the lineItem
on FulfillmentOrderLineItem
without planning for deprecation. This applies to all API versions.
Learn more about FulfillmentOrderLineItem.lineItem
on Shopify.dev.
October 07, 2024
Updated CalculateExchangeLineItemInput and CalculatedExchangeLineItem Variant nullability API
As of Admin GraphQL API 2025-01
version, CalculateExchangeLineItemInput.variantId
and CalculatedExchangeLineItem.variant
fields are nullable at schema level.
This is in preparation of future feature changes. In the current state CalculateExchangeLineItemInput.variantId
will still be validated via a returned error if not present.
Learn more about CalculateExchangeLineItemInput and CalculatedExchangeLineItem.
October 04, 2024
Add accountOpenerName
to shopifyPaymentsAccount
API
As of GraphQL Admin API version 2025-01, the accountOpenerName
field will be added to shopifyPaymentsAccount
October 02, 2024
Bulk query operation userErrors now includes code field API
As of version 2025-01, the Admin API bulk query operation userErrors
GraphQL type will change to BulkOperationUserError
. The new type includes the same fields as the old type, with the addition of a code
field.
October 01, 2024
Shopify Payments Balance Transaction GraphQL type supports advance and advance funding type API
As of GraphQL Admin API version 2024-10, ShopifyPaymentsTransactionType now includes ADVANCE
and ADVANCE_FUNDING
type.
Learn more about ShopifyPaymentsTransactionType
on Shopify.dev.
October 01, 2024
Exposing Business Entity fields on Admin API API
As of GraphQL Admin API version 2024-10, Business Entity attributes will be available for use as a GraphQL object and across relevant types.
You will now be able to query for properties related to the Business Entities that are enabled on your shop and request for these fields on objects that can be associated to a Business Entity.
Business Entity identifiers will also be available on the Order REST Admin API version 2024-10 as well as on webhook payloads.
October 01, 2024
Shopify Payments GraphQL Admin API supports querying a list of disputes API
As of GraphQL Admin API version 2024-10, querying for all disputes for a given shop will be available for use as a GraphQL connection.
Learn more about ShopifyPaymentsDispute
on Shopify.dev
October 01, 2024
Added variant_strategy
for productOptionsCreate
API
In the version 2024-10 release of the Admin GraphQL API, the productOptionsCreate
mutation will include a variantStrategy
parameter, enhancing control over variant management when adding new product options. This new parameter allows for two strategies:
LEAVE_AS_IS
: Maintains existing variants, updating them to include new option values without creating new variants as necessary.CREATE
: Generates new variants for all possible combinations of option values. This enhancement allows for more precise control over product variant configuration and inventory management.
For more detailed information and examples, visit our productOptionsCreate documentation on Shopify.dev.
October 01, 2024
Adding requiresComponents
field to ProductVariantsBulkInput
API
As of the 2024-10 version of the GraphQL Admin API, the requiresComponents
field available in ProductVariantInput
has been added to ProductVariantsBulkInput
.
This field allows variants to be marked as bundles that require components in order to be sold.
Learn more about requiresComponents
and ProductVariantsBulkInput
on Shopify.dev.
October 01, 2024
New CollectionsCount
query in the GraphQL Admin API
API
As of 2024-10
version, we are adding CollectionsCount
query to the Admin GraphQL API.
Learn more about CollectionsCount on Shopify.dev.
October 01, 2024
Metafield Definition Webhooks API
As of GraphQL Admin API Version 2024-10, you can subscribe to MetafieldDefinition changes under the webhook topics metafield_definitions/create
, metafield_definitions/update
, and metafield_definitions/delete
October 01, 2024
ShopifyPaymentsBankAccount GraphQL Admin API unused fields removed API
As of GraphQL Admin API version 2025-01, we're cleaning up the shopifyPaymentsBankAccount
endpoint and removing several unused fields.
October 01, 2024
Storefront API support for Combined Listings API
Merchants using the Storefront API can now offer Combined Listings with Shopify. The Shopify Combined Listings app is available to merchants on Plus plans, helping merchants better merchandise products that come in multiple variations such as colors, materials or lengths, all from the same product listing.
Learn more about the Shopify Combined Listings app in the Shopify Help Center.
October 01, 2024
Added new field recurring_cycle_limit
and applies_on_subscription
to DiscountAutomaticApp and DiscountAutomaticAppInput
API
As of 2024-10
, you can use the recurring_cycle_limit
and applies_on_subscription
field on the DiscountAutomaticApp object type so that subscriptions can use function based discounts for a specified number of occurrences
Learn more about DiscountAutomaticApp
on Shopify.dev.
October 01, 2024
New has_variants_that_requires_components
field on Product Webhooks
API
As of 2024-10, the product create and update webhook payloads contain information indicating if the product has a variant that is a product bundle.
The new boolean field, has_variants_that_requires_components
, mirrors what is already available on the Product GraphQL response.
To receive has_variants_that_requires_components
in the webhook payload, specify 2024-10 or greater as the webhook API version in your App Partner Dashboard.
Learn more about Product Bundles.
October 01, 2024
New field and queries for the StaffMember
object in the GraphQL Admin API
API
The 2024-10
version of the GraphQL Admin API brings improvements to the StaffMember
object:
- New
accountType
field. - You can retrieve the staff member making the API request with the
currentStaffMember
query. - You can list all staff members with the
staffMembers
connection query. Shop.staffMembers
was deprecated in favor of thestaffMembers
query.
This allows apps using the User
REST Admin API resource to migrate to GraphQL's StaffMember
object.
October 01, 2024
Action required
Removal fulfillment service shipping method API
As of 2024-10, you can no longer use the deprecated shippingMethods
field on the fulfillmentService
query or include it as an argument in the fulfillmentOrderSubmitFulfillmentRequest mutation
.
The shipping method associated with the fulfillment service provider applied only to Fulfill By Amazon fulfillment service. The Fulfillment by Amazon feature is not supported as of March 30, 2023. To continue using Amazon fulfillment, merchants need to set up a Multi-Channel Fulfillment solution recommended by Amazon.
To learn more see https://help.shopify.com/manual/shipping/fulfillment-services/amazon#activate-fulfillment-by-amazon
October 01, 2024
New mutation to create an order API
As of GraphQL Admin API 2024-10 version, you can make use of a new mutation to create an order.
Learn more about orderCreate
on Shopify.dev.
October 01, 2024
POS UI Extensions 2024-10 Update API
As of October 1, we added the following updates to POS UI Extensions:
- Added support for iOS debugging with the Safari dev tools.
- Added support for the
pos.product-details.block.render
target. - Added support for the
pos.purchase.post.block.render
target. - Added support for the
pos.order-details.block.render
target. - Added support for the
pos.customer-details.block.render
target. - Introduced a
POSBlock
component. It's the required parent component for block extension targets. - Introduced a
POSBlockRow
component. It's the required child component forPOSBlock
, and can be used to wrap other components. - Deprecated the
ActionItem
component. Please use theButton
component instead. - Added support for windowed modals.
All of the changes are available for POS UI extensions version 2024-10 and POS app version 9.19.0. See the version log for all version details.
October 01, 2024
Fulfillment Constraints now support Local Pickup API
As of Admin GraphQL API version 2024-10
and unstable
, you can setup your Fulfillment Constraint function to run for Local Pickup delivery method.
Use the FulfillmentConstraintRuleCreate mutation to register your new Fulfillment Constraint function with the PICK_UP
delivery method.
Or, use the FulfillmentConstraintRuleUpdate mutation to update your existing registered function to include PICK_UP
.
October 01, 2024
Admin API update on fulfillmentOrder.destination
and FulfillmentOrderDestination
object
API
Breaking Changes
As of the Admin API version 2024-10 and unstable release, fulfillmentOrder.destination
will return a FulfillmentOrderDestination
object instead of null
for fulfillment orders lacking an associated shipping address. In such cases, the address related fields within the FulfillmentOrderDestination
object will be set to null.
Non Breaking Changes
As of GQL Admin API version 2024-10 and unstable release, you can use new field fulfillmentOrder.destination.location
to retrieve the pickup location for the fulfillment order.
You can learn more about fulfillmentOrder.destination
here and fulfillmentOrderDestination
here
October 01, 2024
Action required
Fulfillment Constraints can now be associated with one or multiple delivery methods API
You can now associate a Fulfillment Constraint function with one or multiple delivery method types. The function will only run within the context of those specific delivery methods.
As of Admin GraphQL API version 2024-10
and unstable
, you can
- Use the FulfillmentConstraintRuleCreate mutation to register your new Fulfillment Constraint function and associate it with one or multiple delivery methods. A new required input field
delivery_method_types
will be added. - Use the FulfillmentConstraintRuleUpdate mutation to update delivery method(s) for an existing registered function.
Existing fulfillment constraint functions will continue to run for SHIPPING
, LOCAL
and PICKUP_POINT
.
October 01, 2024
Action required
Removal of the priceRule
resource from GraphQL Admin API
API
As of 2024-10
, the priceRule
resource is being removed. The queries and mutations have been deprecated since 2023-03
.
The discount resource can be used to achieve the same operations.
October 01, 2024
Action required
Breaking changes to returns API: Deprecate reverseDeliveryDispose
mutation
API
As of GraphQL Admin API version 2024-10, the reverseDeliveryDispose
mutation will be deprecated. Use the reverseFulfillmentOrderDispose
mutation instead.
Learn more about managing reverse fulfillment orders on Shopify.dev.
October 01, 2024
New CompanyLocationStaffMemberAssignments API endpoints for managing staff member assignments on a Company Location API
As of 2024-10, we've added a CompanyLocationStaffMemberAssignment
to the CompanyLocation
object for viewing the staff members assigned to the company location.
You can assign and remove staff members for a company location using the CompanyLocationAssignStaffMembers
and CompanyLocationRemoveStaffMembers
mutations.
October 01, 2024
Notify customers when their return requests are approved or declined API
As of the 2024-10 API version, you can notify customers that their return request was approved or declined.
You can submit a notifyCustomer
argument when approving a return request using the returnApproveRequest
mutation.
You can also submit a notifyCustomer
argument when declining a return request using the returnDeclineRequest
mutation. To include a custom message to the buyer in the email notification, use the declineNote
argument.
When notifyCustomer
is true
, an email notification is sent to the Order.email
. If this field is null, the notification is not sent.
October 01, 2024
Action required
Exposing the order adjustments connection on a Refund API
As of the 2024-10 Admin GraphQL API, you can use the Refund.orderAdjustments
connection to query for the difference between calculated and actual refund amounts. The REFUNDS_CREATE
webhook topic will include order adjustments too. As of 2024-10, the webhook payload for REFUNDS_CREATE
will not include the kind
field.
Please note that the OrderAdjustment.kind
field is now deprecated in the Admin GraphQL API. It is also deprecated in the legacy refund.order_adjustments
resource in the Admin REST API.
For this reason, refunded shipping costs will not be included in the Refund.orderAdjustments
connection. To query for refunded shipping costs, use the Refund.refundShippingLines
connection instead. This connection has been updated as of July 18, 2024 to include refunded shipping costs; more info here. Refunded shipping costs will not be present in the webhook payload for REFUNDS_CREATE
as of 2024-10 for the same reason.
The OrderAdjustment.kind
field will be present on the unstable
API version for 6 months to allow apps to migrate to the 2024-10 API version.
October 01, 2024
Admin API includes discountNodesCount
API
As of Admin GraphQL API version 2024-10
, you can access the QueryRoot.discountNodesCount
field to retrieve the total count of discounts in the shop.
Learn more about discountNodesCount
on Shopify.dev.
October 01, 2024
Introducing Payment Groups and Sessions to SubscriptionBillingAttempts API
As of GraphQL Admin API version 2024-10, the SubscriptionBillingAttempt object will have two new fields: paymentgroupid and paymentsessionid.
This will allow your subscription apps to have better insights into how billing attempts correlate for merchant-facing statistics.
The payment group is defined as: - Attempts belonged to the same subscription contract identity. - The attempts were all failures, or ended in a success. If two sequential successes occur with all the same attributes, then they're treated as separate groups. It can be used for correlated retried billing attempts together.
The payment session for subscriptions is defined as: - Attempts used the same payment group - Attempts used the same payment method - Attempts used the same currency - Attempts were for the same amount We expect any merchant facing statistics regarding payment success rates to only show a single success or failure per paymentsessionid.
October 01, 2024
Introducing Session ID to StartPaymentSession API
As of Payments Apps API version 2024-10, the StartPaymentSession payload for all payment extension types will have one new field: session_id.
This identifier is shared across payment sessions that belong to the same payment group, buyer session, and share payment details. It can be used to power auth rate calculations.
October 01, 2024
Localized fulfillment hold reason on FulfillmentHold
API
We've added a new localized string field displayReason
to FulfillmentHold
so that you can query for a human-readable reason when a fulfillment is on hold.
October 01, 2024
Add new theme-related fields to TranslatableResourceType
enum
API
As of API version 2024-10
, you can use these new fields to TranslatableResourceType
that are related to the online store theme: ONLINE_STORE_THEME_JSON_TEMPLATE
, ONLINE_STORE_THEME_SECTION_GROUP
, ONLINE_STORE_THEME_APP_EMBED
, ONLINE_STORE_THEME_LOCALE_CONTENT
, ONLINE_STORE_THEME_SETTINGS_CATEGORY
and ONLINE_STORE_THEME_SETTINGS_DATA_SECTIONS
Together, these new types will cover the translatable content and translations within the existing ONLINESTORETHEME enum type and offer more granularity with respect to the returned data. They are introduced with the intent of reducing the use of ONLINE_STORE_THEME
type in the future, so that we do not return the entirety of a theme's content when it is not needed.
We are also introducing a nestedTranslatableResources
connection under TranslatableResource
object. When used with a ONLINE_STORE_THEME
type TranslatableResource
, the theme resources that belong to this particular theme are exposed.
-->
October 01, 2024
Translatable content that is specific to a market context is now exposed API
As of API version 2024-10
, you can use the marketId
argument to retrieve translatable content that is specific to a market. Concretely, combined with ONLINE_STORE_THEME_JSON_TEMPLATE
and ONLINE_STORE_THEME_SECTION_GROUP
translatable resource types, you can retrieve translatable content within the added sections and blocks in a contextualized theme template or theme section group for a specfic market. More details can be found here about customizing a theme for specific markets.
October 01, 2024
Action required
Adding pagination arguments to Customer addresses API
As of GraphQL Admin API version 2024-10, the addressesV2
field is introduced on the Customer
object to support paginating through a customer's addresses.
Learn more about the Customer
fields on Shopify.dev.
October 01, 2024
GraphQL support to send customer account invite API
As of GraphQL Admin API version 2024-10, you can use the customerSendAccountInviteEmail
mutation to send an email invite to create a classic customer account.
October 01, 2024
New customer account pages now available in menus via Admin API API
As of API version 2024-10, you can add links to the Orders, Profile, and Settings pages to navigation menus.
To learn more, refer to menuCreate, menuUpdate and menu
October 01, 2024
New abandoned checkouts listing endpoint on the admin GraphQL API API
As of 2024-10, you can use the abandonedCheckouts
endpoint to get the list of abandoned checkouts of a shop. This will replace the current REST endpoint.
October 01, 2024
Subscription Contract fields now fully available on the Customer API API
As of the 2024-10 release of the GraphQL Customer API, you can now query the following fields for a customer's subscription contracts using the subscriptionContracts
or subscriptionContract
fields:
* linesCount
* billingPolicy
* deliveryPolicy
* deliveryMethod
* deliveryPrice
* updatedAt
* currencyCode
We’ve also added support for the following connections: * lines * orders
The customer_read_own_subscription_contracts
permission is now required to query subscription contracts and the customer_write_own_subscription_contracts
permission is now required for subscription contract mutations.
Learn more about subscription contracts on the Customer API at Shopify.dev.
October 01, 2024
New created_fulfillment_hold
field on fulfillment_orders/placed_on_hold
webhook
API
As of Admin API version 2024-10, you can use the created_fulfillment_hold
field on fulfillment_orders/placed_on_hold
webhook to see the fulfillment hold that was created.
Why was this field added
A fulfillment hold gets deleted when a hold is released. It is possible that the FulfillmentOrder.FulfillmentHolds
field will be empty by the time the subscriber receives the webhook. The new field created_fulfillment_hold
will always show hold that was created regardless of whether it has already been released/deleted.
Learn more about fulfillment_orders/placed_on_hold
webhook on Shopify.dev.
October 01, 2024
Action required
New field and permission update to fulfillment hold resource API
As of the GraphQL Admin API version 2024-10, a heldByRequestingApp
field is being added to the FulfillmentHold
GraphQL resource.
As of the GraphQL Admin API version 2024-10, you will only be able to read the heldBy
field on the FulfillmentHold
GraphQL resource if you have read_apps
scope enabled on your application. Use the heldByRequestingApp
boolean field instead if you need to see if your application created the fulfillment hold.
Learn more about FulfillmentHolds.