> [!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:
>
> 1. Recommended Option: switch to the Storefront API Client
> 1. 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.
> 2. Stopgap Option: Upgrade to JS Buy SDK v3.0
> 1. 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

$3

To upgrade simply run either of the following commands

With npm:

``bash
npm install shopify-buy@3
`

With Yarn:

`bash
yarn add shopify-buy@3
`

CDN:

`html

`

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.

`html

`

$3

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.

$3

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

$3

---

!Build

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
- Examples
- Initializing the Client
- Fetching Products
- Fetching Collections
- Expanding the SDK
- Initializing the Client
- Fetching Products
- Example Apps
- Documentation
- Contributing
- Code of Conduct
- License

Builds

The JS Buy SDK has four build versions: ES, CommonJS, AMD, and UMD.

ES, CommonJS:

`javascript
import Client from "shopify-buy";
`

AMD:

`javascript
import Client from "shopify-buy/index.amd";
`

UMD:

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

`javascript
import Client from "shopify-buy/index.unoptimized.umd";
`

Examples

$3

If your store supports multiple languages, Storefront API can return translated resource types and fields. Learn more about translating content.

`javascript
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",
});
`

$3

`javascript
// 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);
});
`

$3

`javascript
// 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.

$3

`javascript
// 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",
});
`

$3

`javascript
// 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

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