Shopify
[!CAUTION]
Deprecation notice
Note: The JS Buy SDK is deprecated as of January, 2025. It will no longer be updated or maintained by Shopify past that point. A final major version, v3.0, has been released to remove the SDK's dependency on the deprecated Checkout APIs, replacing them with Cart APIs. Updating to this new version will allow the SDK to continue to function for most use cases.
If you are using the JS Buy SDK, you have two options:
- Recommended Option: switch to the Storefront API Client
- The Storefront API Client manages the API's authentication information and provides various methods that enable devs to interact with the API. This is the preferred and more future-proof solution. See this migration guide to help you transition.
- Stopgap Option: Upgrade to JS Buy SDK v3.0
- This allows you to maintain your current setup with minimal changes for use cases that are supported by the Cart API. A migration guide with details on supported use cases will be available soon. If you choose this option, we still recommend that you switch to the Storefront API Client in the future.
Critical Deadline: July 1st, 2025. You must implement one of these changes by this date, or customers will not be able to complete purchases. Please choose the option that best suits your needs and timelines.
Shopify JavaScript Buy SDK
2.x -> 3.0 Migration guide
How to upgrade to v3.0?
To upgrade simply run either of the following commands
With npm:
npm install shopify-buy@3With Yarn:
yarn add shopify-buy@3CDN:
<script src="https://sdks.shopifycdn.com/js-buy-sdk/v3/latest/index.umd.min.js"></script>You can also fetch the unoptimized release. This will be larger than the optimized version, as it will contain all fields that are available in the Storefront API. This should only be used when you need to add custom queries to supplement the JS Buy SDK queries.
<script src="https://sdks.shopifycdn.com/js-buy-sdk/v3/latest/index.unoptimized.umd.min.js"></script>How to validate that I am using v3.0?
To validate that the upgrade was successful or that your are using v3.0, open your package.json and make sure the shopify-buy dependency is set to 3.0.0 or higher.
In addition, you can check that the client is using the Cart API by monitoring the network tab on your preferred developer tools when adding an item to the cart. If you see that the operation performed was cartCreate, cartLinesUpdate, or cartLinesAdd rather than checkoutCreate, then you are using v3.0.
How will I know my ecommerce experience will still work after I take action?
If you migrate to Storefront API Client, there is virtually no use case that can’t be addressed with the right technical implementation. Upfront planning and following the migration guide will be critical to a smooth successful migration. If you decide to switch to JS Buy SDK v3.0, the majority of use cases should still work successfully, but there's no guarantee it will work with future Shopify features. Additionally, there are several fields that are no longer compatible:
[!NOTE] If you don't use any of these fields, you only have to bump the package version and everything will work.
Fields no longer supported
| field | compatibility | notes | solution? |
|---|---|---|---|
| completedAt | ⚠️ | Not supported. Defaults to null |
The Cart API does not maintain the state of a completed Cart that became an order. |
| order | ⚠️ | Not supported. Defaults to null |
To retrieve customer orders, please use either the Customer Account API or the legacy Customer API. |
| orderStatusUrl | ⚠️ | Not supported. Defaults to null |
Same as above |
| ready | ⚠️ | Not supported. Defaults to false |
The Cart API only returns carts that are considered ready. Simply bypass or remove any existing code depending on this field. |
| requiresShipping | ⚠️ | Not supported. Defaults to true |
The Cart API does not contain shipping information, this is currently handled in the Checkout flow. Remove any existing code depending on these fields. |
| shippingLine | ⚠️ | Not supported. Defaults to null |
Same as above |
| taxExempt | ⚠️ | Not supported. Defaults to false |
The Cart API is not tax aware, as taxes are currently handled in the Checkout flow. Remove any existing code depending on this field. |
| taxesIncluded | ⚠️ | Not supported. Defaults to false |
Same as above |
| discountApplications | ✅⚠️ | If a buyer's shipping address is unknown and a shipping discount is applied, shipping discount information is no longer returned | In this situation, the Cart API does not return any information about the value of the shipping discount (eg: whether it's a 100% discount or a $5 off discount) |
Updated .checkout methods
The updated checkout interface supports all existing methods with some limitations:
| method | compatibility | notes |
|---|---|---|
| fetch | ✅ | |
| create | ✅⚠️ | - Does not create localized checkouts when passing presentmentCurrencyCode - Does not localize an empty checkout created with buyerIdentity.countryCode. (Must create with lineItems) |
| updateAttributes | ✅⚠️ | - Does not update a checkout to support allowPartialAddresses |
| updateEmail | ✅ | |
| addLineItems | ✅ | |
| replaceLineItems | ✅ | |
| updateLineItems | ✅ | |
| removeLineItems | ✅ | |
| addDiscount | ✅ | - Does not apply order-level discounts to an empty checkout |
| removeDiscount | ✅ | |
| addGiftCards | ✅ | |
| removeGiftCard | ✅ | |
| updateShippingAddress | ✅ |
FAQ
We know the important role the JS Buy SDK library played in allowing merchants to create ecommerce experiences. When it was first released in 2016, our main priority was to provide quick and easy ways to interact with our GraphQL APIs. However, over the years, a lot has changed and the SDK is no longer the optimal client to fully leverage all of Shopify capabilities.
You have multiple options: a) switch to the Storefront API Client, our recommendation and more future-proof solution; see our migration guide to help you transition, and also take a look at the Storefront API Client docs and npm package or b) upgrade to JS Buy SDK v3.0, our last and final release of the JS Buy SDK library. See this upgrade guide to install v3.0. c) switch to one of our other solutions.
Shopify has evolved since the JS Buy SDK was first released, so we encourage you to explore and determine if one of our themes for an Online Store is a better fit for your needs. This action must be completed before July 1, 2025 11:00 AM ET.
The only functionality that should be affected by the upgrade to JS Buy SDK v3.0 is the cart and checkout. For example, customers can’t complete purchases or the website crashes when a customer attempts to add to cart or view their cart. Other possible issues could be related to any existing workflows that rely on the .order, .completedAt or any other no longer supported Checkout specific fields. We have set these fields to their default values to mitigate any breaking changes, but we can’t guarantee all existing functionality.
If you are experiencing issues, we recommend you check if you are using any fields that are no longer supported in v3.0.
You may be using one of the fields that are no longer supported in JS Buy SDK v3.0. If you are not a developer, we recommend contacting the people who last worked on your store, whether that was to initially build it or help maintain it over time. If you are looking to work with an agency, check out our partner directory for more information.
Buy Buttons that were created through the Shopify Admin Buy Button channel will work without any intervention and there is no action required. The Buy Button JS library will be updated to use v3.0 of JS Buy SDK and users of the library will need to upgrade their version of Buy Button JS.
If your store is affected, you will have received an email from us. Another way to verify is to search for shopify-buy in your codebase or the snippets you embedded into your site. If this is not possible, then we recommend contacting a third-party provider or search our partner directory for support.
We’d recommend reviewing our changelog to first upgrade your store to v2.22.0 of the JS Buy SDK, and then upgrade to v3.0 after that. In addition, we are constantly evolving our solutions and we encourage you to explore them and see if one might better fit your needs.
If you do not take any action before July 1, 2025 11:00 AM ET, your store will lose the ability for customers to complete purchases and your site may become unavailable for users with existing carts.
All merchants using JS Buy SDK will be granted an automatic one-time extension to complete the switch to v3.0 before July 1, 2025 at 11:00 AM ET. The JS Buy SDK v3.0 update removes the dependency on Checkout APIs and replaces them with Cart APIs. This means that when you call methods on the Checkout resource, they’ll use Cart APIs instead. We did our best to keep the inputs and outputs the same, but some features from the Checkout APIs do not have a Cart API equivalent, so please test thoroughly after upgrading.
JS Buy SDK v3.0 will be supported until January 1, 2026. Upgrading to JS Buy SDK v3.0 should be considered a short-term solution before implementing a long-term solution such as Storefront API Client, Hydrogen, or Storefront Web Components or Online Store Editor.
This option is the easiest and fastest way to remain functional and give you more time to consider, plan, and implement a better long-term solution such as using the Storefront API Client.
This will heavily depend on your ecommerce experience and what level of technical resources you have available. If you do not have access to technical resources or are unsure where to begin, you can review the migration guide, or contact a third-party agency who could provide consultation.
Once you have updated your project to use v3.0, you can check your package.json to ensure that the shopify-buy dependency is now at 3.0.0 or higher. In addition you can check that the client is using the Cart API by monitoring the network tab of your preferred developer tools when adding a line item to the cart. If you see that the operation performed was cartCreate, cartLinesUpdate, or cartLinesAdd rather than checkoutCreate, then you have switched to v3.0 successfully. More information
Migrating to the Storefront API Client is a great way to future-proof your ecommerce experience by gaining full control over how your store interacts with Shopify APIs. You will get access to globally-deployed Carts, offering improved performance, scalability, and a richer feature set including subscriptions, product bundles, contextual pricing, Shopify Functions, UI extensions, and more. In addition, we have other solutions available that might better fit your needs Hydrogen, or Storefront Web Components or Online Store Editor.
The Checkout API is deprecated. To find the legacy documentation for v2.x, you can visit this page.
The JS Buy SDK is a lightweight library that allows you to build ecommerce into any website. It's based on Shopify's Storefront API and provides the ability to retrieve products and collections from your shop, add products to a cart, and checkout.
Full API docs are available here.
Changelog
View our Changelog for details about our releases.
SDK Version Support
Each version of the JS Buy SDK uses a specific Storefront API version and the support of an SDK version is directly linked to the support of the corresponding Storefront API version. Storefront API versioning information can be found here.
Table Of Contents
Builds
The JS Buy SDK has four build versions: ES, CommonJS, AMD, and UMD.
ES, CommonJS:
import Client from "shopify-buy";AMD:
import Client from "shopify-buy/index.amd";UMD:
import Client from "shopify-buy/index.umd";UMD Unoptimized: This will be larger than the optimized version, as it will contain all fields that are available in the Storefront API. This should only be used when you need to add custom queries to supplement the JS Buy SDK queries.
import Client from "shopify-buy/index.unoptimized.umd";Examples
Initializing the Client
If your store supports multiple languages, Storefront API can return translated resource types and fields. Learn more about translating content.
import Client from "shopify-buy";
// Initializing a client to return content in the store's primary language
const client = Client.buildClient({
domain: "your-shop-name.myshopify.com",
storefrontAccessToken: "your-storefront-access-token",
});
// Initializing a client to return translated content
const clientWithTranslatedContent = Client.buildClient({
domain: "your-shop-name.myshopify.com",
storefrontAccessToken: "your-storefront-access-token",
language: "ja-JP",
});Fetching Products
// Fetch all products in your shop
client.product.fetchAll().then((products) => {
// Do something with the products
console.log(products);
});
// Fetch a single product by ID
const productId = "gid://shopify/Product/7857989384";
client.product.fetch(productId).then((product) => {
// Do something with the product
console.log(product);
});
// Fetch a single product by Handle
const handle = "product-handle";
client.product.fetchByHandle(handle).then((product) => {
// Do something with the product
console.log(product);
});Fetching Collections
// Fetch all collections, including their products
client.collection.fetchAllWithProducts().then((collections) => {
// Do something with the collections
console.log(collections);
console.log(collections[0].products);
});
// Fetch a single collection by ID, including its products
const collectionId = "gid://shopify/Collection/369312584";
// Set a parameter for first x products, defaults to 20 if you don't provide a param
client.collection
.fetchWithProducts(collectionId, { productsFirst: 10 })
.then((collection) => {
// Do something with the collection
console.log(collection);
console.log(collection.products);
});Expanding the SDK
Not all fields that are available on the Storefront API are exposed through the SDK. If you use the unoptimized version of the SDK, you can easily build your own queries. In order to do this, use the UMD Unoptimized build.
Initializing the Client
// fetch the large, unoptimized version of the SDK
import Client from "shopify-buy/index.unoptimized.umd";
const client = Client.buildClient({
domain: "your-shop-name.myshopify.com",
storefrontAccessToken: "your-storefront-access-token",
});Fetching Products
// Build a custom products query using the unoptimized version of the SDK
const productsQuery = client.graphQLClient.query((root) => {
root.addConnection("products", { args: { first: 10 } }, (product) => {
product.add("title");
product.add("tags"); // Add fields to be returned
});
});
// Call the send method with the custom products query
client.graphQLClient.send(productsQuery).then(({ model, data }) => {
// Do something with the products
console.log(model);
});Documentation
Contributing
For help on setting up the repo locally, building, testing, and contributing please see CONTRIBUTING.md.
Code of Conduct
All developers who wish to contribute through code or issues, take a look at the CODE_OF_CONDUCT.md.
License
MIT, see LICENSE.md for details.
