Developer changelog

As of the 2022-10 version of the Admin GraphQL API, you can use the contextualPricing field on Product and ProductVariant to fetch prices for a CompanyLocation by passing a companyLocationId argument to the context input.

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

As of GraphQL Admin API version 2022-10, you will get access to new fields and mutations for draft orders.

In particular, you will now be able to: - Duplicate drafts - Creating drafts from orders - Execute bulk operations such as add/remove tags and deleting drafts - Create drafts with inventory reservations - Access previously hidden fields, such as metafields, on drafts and line items

Learn more about DraftOrderCreate.

As of 2022-10, partners can manage the delivery methods of the subscriptions contracts with Shipping, Local Delivery, and Pickup.

SubscriptionContract.deliveryMethod supports two new types: SubscriptionDeliveryMethodLocalDelivery and SubscriptionDeliveryMethodPickup.

A new SubscriptionDraft.deliveryOptions provides a SubscriptionDeliveryOptionResultSuccess type for all three delivery methods.

To edit or create contracts, an extended SubscriptionDeliveryMethodInput for SubscriptionDraftInput can receive localDelivery and pickup information.

Important to note:

• SubscriptionContract.deliveryMethod returns null for clients using API versions earlier than 2022-10 when the contract is created with Local Delivery or Pickup. If you have been inferring a subscription has only digital products because the delivery method is null, then adopt our new graphql changes.
• We also recommend taking a look at general delivery terms your app might be using, such as “delivers” or “ships”. Consider replacing them with broader terminology like “fulfills” or “recurs” that cover all modes of delivery.

Learn more about Delivery Methods for Subscription on Shopify.dev.

As of 2022-10 you can now add, remove and view MarketWebPresence associated with a Locale through the ShopLocale GraphQL endpoints.

Learn more about ShopLocale and [MarketWebPresence].(https://shopify.dev/api/admin-graphql/2022-10/objects/MarketWebPresence).

As of GraphQL API 2022-10, two new metafield definition types are available:

• collection_reference: A reference to a collection on the online store.
• list.collection_reference: A list of collection references on the online store.

Learn more about the new reference types in Shopify.dev, and see examples.

As of 2022-10 in GraphQL Admin API version unstable, you can use the new Local Pickup mutations to:

Enable Local Pickup for a location

Disable Local Pickup for a location

Additionally, you can access the current Local Pickup settings using the new Location.localPickupSettingsV2 field.

This enables you to fully manage Local Pickup settings for a location!

Learn more about Local Pickup on Shopify Help Center.

As of Shopify CLI version 3.13.0, you can now preview theme app extensions by running the dev command. Shopify CLI supports hot reloading for theme app extensions, so you can avoid refreshing the browser after making changes.

Learn more about previewing theme app extensions.

The Product Recommendations API now supports an intent parameter that allows theme developers to specify whether they want to show related or complementary products.

Complementary products are a new type of product recommendation intended for items that are often bought together or pair well. Complementary products can be set with the Search & Discovery app.

Learn more about the product recommendation intents on Shopify.dev

We've added a new Rails association to Product and use it in the Product GraphQL, so that the database queries use an indexed access path, rather than doing a full table search as is being done now.

There's no change to the API.

As of September 19, 2022, you can use a new set of endpoints in the GraphQL Admin API 2022-10 version to surface custom content to buyers in a specific market that is not language based.

The newly introduced endpoints are marketLocalizableResource, marketLocalizableResources and marketLocalizableResourcesByIds queries, as well as marketLocalizationsRegister and marketLocalizationsRemove mutations.

An example of market localizable content that is not language based is the newly introduced money content type metafield

You can now use authenticated access to make Storefront API requests from a server (for example, from a Hydrogen server).

Using authenticated access enables more throughput for your server than using a public token, and enables Shopify's bot protection features to work more effectively.

The Shopify admin is moving to a new domain: admin.shopify.com. Embedded apps should migrate to App Bridge 3.0 as soon as possible to ensure the best merchant experience in this new domain.

The following requirements must be met for embedded apps to load in admin.shopify.com. Until these requirements are met, merchants will be forced to redirect to the old admin domain to use the app:

1. The content security policy includes admin.shopify.com.
2. The app is on App Bridge 2.0.5 or higher, and has correctly implemented the host parameter. App Bridge 3.0 is recommended.

New fields have been added to the app listing in preperation for the updated app listing page. All developers must complete the updated form by November 1. For more information on the new form, click here

App categories are getting simplified for better merchant discovery. Starting in November, you’ll be able to categorize your own app. For more information, click here

As of 2022-10 the marketWebPresenceUpdate endpoint now supports adding unpublished locales as alternateLocales.

Learn more about marketWebPresenceUpdate.

As of ** 2023-01 ** version on the Admin GraphQL schema, you can use the DelegateAccessTokenDestroy mutation to delete the delegate tokens created by the API client.

For app architectures that use delegate tokens from multiple subsystems, this makes it easy to remove those delegate tokens that are unused or leaked for better application security.

As of the 2022-10 release of the Storefront API, you can now query a shop's brand settings and assets via the new Shop.brand field.

For more information on configuring your shop's brand settings, click here.

Starting October 3rd, Plus Merchants who customize their checkout via Checkout Extensibility will be required to use the new Web Pixel Extension instead of adding checkout.liquid code.

Ensure your app can support these merchants' measurement goals by building with the Web Pixel Extension. This will unlock additional locations for adding pixels, such as checkout, while increasing data accuracy, and providing tools for privacy compliance.

Visit the developer documentation to learn more and build with pixels.

Icons added to your app using the Partner Dashvoard App setup page now must be 1200 px by 1200 px in size. This change makes icon sizes consistent across the Partner Dashboard, the Shopify App Store, and other development surfaces.

Shopify now supports automatically optimizing storefront images using the AV1 Image File Format (AVIF) format, which improves performance by reducing delivered bytes. Optimization occurs on a per image basis, where Shopify will examine the request and determine the best compatible file format (e.g. AVIF, WebP or JPEG) based on image quality and compressed bytes.

You can learn more by visiting https://cdn.shopify.com/

As of 2022-10, the Money scalar is being removed from the Storefront API. It was previously used for monetary fields that do not have a V2 suffix (<name>: Money). As a result, the following changes are being made: * Non-V2 fields will now use MoneyV2 objects for their type (<name>: MoneyV2). * Monetary fields that do have the V2 suffix (<name>V2: MoneyV2) are being deprecated in favor of the <name>: MoneyV2 equivalent. These fields will be removed in subsequent releases.

These changes will help improve consistency of the API and avoid confusion when using these fields.

Hey all! Coming back at you with improvements to creating an app from the Partner Dashboard! We’re removing the need for you to enter in any kind of URL when you’re manually creating an app from the UI. Instead, we’ll generate placeholders for you in the App setup area. You can update these URLs when you're ready to test or distribute your app.

We’ve also added a new Insights section to the app navigation, so you can discover everything from app history to API health without having to hunt around!

SellingPlanGroup and SellingPlan fields will be supported by the Translations API as translatable resources. The following fields will be available in the unstable API until the 2022-10 API release:

• SellingPlanGroup.name - Public-Facing Name of the Selling Plan Group
• SellingPlan.description - Optional, more verbose description of the Selling Plan
• SeillingPlan.option1 - Delivery frequency
• SellingPlan.option2- Delivery frequency (optional)
• SellingPlan.option3 - Delivery frequency (optional)

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

We've made changes to our Partner Program Agreement. This includes terms noting that all apps may only be installed or otherwise initiated directly on or through applicable Shopify surfaces allowing us to help provide merchants the trust signals they need to make informed choices, as well as other updates.

These changes come into effect as of today, August 03, 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.

As of today, theme app extensions are be able to store translations up to 15 KB per locale file.

For more information about file and content size limits for theme app extensions, refer to the theme app extension framework documentation.

You may now see new error values and descriptions if you encounter a Braintree payment method being revoked when associating Braintree payment methods with the customers that you import into Shopify.

Learn more about migrating existing subscription contracts to Shopify.

As of the API version 2022-10, upon deleting a reference type metafield definition with delete_all_associated_metafields argument set to false, REFERENCE_TYPE_DELETION_ERROR will be returned with the following error message:

"Deleting a reference type metafield definition requires deletion of its associated metafields."

As of 2022-10 , the following new tax exemption values will be added to the TaxExemption enum and are intended to help with B2B transactions: * United States reseller exemptions, indicating that the merchant is exempt for taxes in a specific state as they are a reseller. * European Union reverse charge exemption, indicating that VAT should not be included on the buyers invoice and that the buyer will be responsible for reporting the correct VAT on their purchase.

Shopify’s GitHub app is requesting write permissions for GitHub Actions. This update will support improvements to the developer experience for Hydrogen custom storefronts hosted on Oxygen.

Today, deployments to the Oxygen hosting platform can only be triggered by committing and pushing a change to a Hydrogen code repository. These additional permissions will enable features such as on-demand re-deploys, automatic branch deployment when creating new Oxygen environments, and other enhancements.

Learn more about Shopify’s GitHub integration.

The customer ID for logged in customers is now included as a parameter in the forwarded query for app proxy requests. The customer ID is passed in the logged_in_customer_id parameter. The parameter will be blank if no customer is currently logged in.

Tip: Make sure that your application is verifying the signature parameter of forwarded queries.

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 Admin API

• ShopifyPaymentsDisputeEvidence object
• ShopifyPaymentsDisputeFileUploadUpdateInput input object
• ShopifyPaymentsDisputeEvidenceFileType enum
• ShopifyPaymentsDisputeFileUpload object
• ShopifyPaymentsDisputeEvidenceUpdate mutation

REST Admin API

• 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 developer documentation.

You can now enable standard metafields on a shop using namespace and key with our GraphQL API.

Learn more about standard metafields.

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.

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.

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.

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.

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.

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.

Location resources now support metafields. Use metafields APIs to store additional information in metafield values, like store hours, and then reference them in Liquid. Note: this is currently supported in our unstable API version only.

To learn more about metafields, refer to the metafields documentation. To use location metafields in Liquid, refer to the store_availability Liquid reference.

The relationship between a ProductVariant and a FulfillmentService was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommended that you no longer use the following fields: ProductVariant.fulfillment_service (REST)(GraphQL) and LineItem.fulfillment_service (REST)(GraphQL). Instead, you should use inventory items and inventory levels if you need to find or manage where a product is stocked.

If you need to determine whether a product is a gift card, you should continue to use the ProductVariant.fulfillment_service field until an alternative is available.

Learn more about managing inventory quantities and states.

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

The following object property on the REST Admin API's Order resource is deprecated:

• total_price_usd

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

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.

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.

The date by which you need to migrate away from the 2022-04 API has been extended to June 30 2023.

Some of the Fulfillment API endpoints and mutations on the Fulfillment API relating to managing fulfillments via an order ID were deprecated in the 2022-04 API release. They have now been removed and replaced by the Fulfillment Orders API in the 2022-07 API release.

This means that your app/integration using the deprecated Fulfillment API endpoints will have until the 2023-07 API release to migrate away from using the deprecated end points. You can continue to use API version 2022-04 until the 2023-07 release.

To help you seamlessly migrate, we've crafted a migration guide that walks you through the process of moving to Fulfillment Orders. To learn more, visit the migration guide on Shopify.dev.

Deprecated Endpoints on the Fulfillment API

https://shopify.dev/docs/api/release-notes/2022-07#fulfillment-endpoints-removed-from-the-rest-admin-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

The relationship between a ProductVariant and a FulfillmentService was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommended that you no longer use the following fields: ProductVariant.fulfillment_service (REST)(GraphQL) and LineItem.fulfillment_service (REST)(GraphQL). Instead, you should use inventory items and inventory levels if you need to find or manage where a product is stocked.

If you need to determine whether a product is a gift card, you should continue to use the ProductVariant.fulfillment_service field until an alternative is available.

Learn more about managing inventory quantities and states.

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.

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.

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

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.

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.

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.

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.