Note: For help with migrating from v0 of JS Buy SDK to v1 check out the -Migration Guide.
+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.
@@ -338,13 +360,13 @@This document provides a set of guidelines for migrating from v0.7 of the JS Buy SDK to v1 of the JS Buy SDK -which uses Shopify's GraphQL-based Storefront API.
-The JS Buy SDK is deprecated. We recommend transitioning to the Storefront API Client to leverage the latest cart features and perform more efficient data retrievals.
+fetchByHandle), which fetch a comprehensive list of fields. Conversely, the Storefront API Client returns only the precise data queried for.data object directly derived from the Storefront API itself.fetchNextPage and automatically fetches all available product images and variant connections by default. The Storefront API Client requires manual pagination.imageForSize helper from JS Buy SDK can be substituted with image.url transform parameters from the Storefront API Client.With Yarn:
-yarn add shopify-buy
-With NPM:
-Remove the old version, then
-npm install shopify-buy
-Rather than using a static function to create the client (ShopifyBuy.buildClient()), v1 exposes the Client
-(previously ShopClient) and a Config class for the Client directly. An instance of Client can be created like so:
Transitioning from the JS Buy SDK to the Storefront API Client involves a few important steps:
+Start by installing the @Shopify/storefront-api-client via your preferred package manager:
npm install @shopify/storefront-api-client
+Transition from the old initialization of the JS Buy SDK:
import Client from 'shopify-buy';
const client = Client.buildClient({
@@ -62,207 +53,158 @@ Initialization
storefrontAccessToken: 'your-storefront-access-token'
});
The functions for fetching products and collections are mostly the same. Major differences are:
-The v1 functions take in a Storefront ID for fetching a product or collection by ID. A Storefront ID can be found under
-the retrieving IDs section of the Storefront API docs.
-Getting Started Guide for the Storefront API.
Collections can be fetched with products using collection.fetchWithProducts(id) (fetches a single collection with associated products) and collection.fetchAllWithProducts() (fetches a page of collections with their associated products).
const collectionId = 'Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzI1NzY5NzczMQ=='
-
-// Use the built-in function
-client.collection.fetchWithProducts(collectionId).then((collection) => {
- console.log(collection); // Collection with all default fields and products with all default fields.
- console.log(collection.products); // Products on the collection
-});
-product.fetchQuery() and collection.fetchQuery() query different fields and take an optional query argument.
-See the product connection field and
-collection connection field docs
-in the storefront API for more details.v0:
-client.fetchQueryProducts({collection_id: '336903494', tag: ['hats']}).then((products) => {
- console.log(products); // An array of products in collection '336903494' having the tag 'hats'
-});
-v1:
-const query = {
- query: 'updated_at:>="2016-09-25T21:31:33"',
- sortBy: 'title'
-};
-
-client.product.fetchQuery(query).then((products) => {
- console.log(products); // An array of products updated after 2016-09-25T21:31:33
- // and sorted in ascending order by title.
-});
-Carts are replaced with checkouts. Like the fetch functions, all checkout functions take an optional query argument that specifies fields to return on the checkout.
fetchRecentCart(), updateModel(), and clearLineItems() have been removed. checkoutUrl has been renamed to webUrl.
To create a checkout, use checkout.create(). You are responsible for capturing the ID of the checkout for later usage. If you would like to persist the checkout between sessions, store the ID in a cookie or localStorage.
v0:
-client.createCart().then((cart) => {
- console.log(cart); // Empty cart
-});
-v1:
-client.checkout.create().then((checkout) => {
- console.log(checkout); // Empty checkout
- console.log(checkout.id); // The ID of the checkout. Store this for later usage.
-});
-The checkout can also be initialized with fields like line items and a shipping address. See the API reference for more details.
-To fetch a checkout, use fetchCheckout().
v0:
-client.fetchRecentCart().then((cart) => {
- console.log(cart); // Most recently created cart
-});
-v1:
-client.checkout.create().then((checkout) => {
- localStorage.setItem('checkoutId', checkout.id); // Store the ID in localStorage
-});
-
-// In another session:
-const checkoutId = localStorage.getItem('checkoutId');
-
-client.checkout.fetch(checkoutId).then((checkout) => {
- console.log(checkout); // The retrieved checkout
-});
-v0:
-client.fetchCart('shopify-buy.1459804699118.2').then(cart => {
- console.log(cart); // The retrieved cart
-});
-v1:
-const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID from a previous checkout.create call
-
-client.checkout.fetch(checkoutId).then((checkout) => {
- console.log(checkout); // The retrieved checkout
-});
-The functions to modify a checkout are on Client rather than CartModel.
To add line items to a checkout, use addLineItems() (previously createLineItemsFromVariants()). Similar to the checkout's ID, you are responsible for storing line item IDs for updates and removals.
v0:
-cart.createLineItemsFromVariants({variant: variantObject1, quantity: 5}, {variant: variantObject2, quantity: 2}).then((cart) => {
- console.log(cart); // Cart with two additional line items
-});
-v1:
-const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID from a previous checkout.create call
-const lineItems = [
- {variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yNTYwMjIzNTk3Ng==', quantity: 5},
- // Line items can also have additional custom attributes
- {
- variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yNTYwMjIzNjA0MA==',
- quantity: 2,
- customAttributes: {'key': 'attributeKey', 'value': 'attributeValue'}
+To the new initialization with the Storefront API Client:
+import {createStorefrontApiClient} from '@shopify/storefront-api-client';
+
+const client = createStorefrontApiClient({
+ storeDomain: 'your-shop-name.myshopify.com',
+ apiVersion: '2024-04',
+ publicAccessToken: 'your-storefront-public-access-token',
+});
+
+Step 3: Convert helper methods to operations
+You'll need to transition from using JS Buy SDK helper methods to a more customized design.
+Fetching products
+JavaScript Buy SDK: Fetching Products
+client.product.fetchAll().then((products) => {
+ // Do something with the products
+ console.log(products);
+});
+
+Storefront API Client: Fetching Products
+const operation = `
+ query {
+ products(first: 10) {
+ edges {
+ node {
+ id
+ handle
+ title
+ }
+ }
+ }
}
-];
-
-client.checkout.addLineItems(checkoutId, lineItems).then((checkout) => {
- console.log(checkout); // Checkout with two additional line items
- console.log(checkout.lineItems) // Line items on the checkout
-});
-
-Updating Line Items
-To update line items on a checkout, use updateLineItems().
-v0:
-const lineItemId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=';
-const quantity = 1;
-
-cart.updateLineItem(lineItemId, quantity).then((cart) => {
- console.log(cart); // Cart with a line item quantity updated to 1
-});
-
-v1:
-const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID from a previous checkout.create call
-const lineItemId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=';
-const lineItems = [
- {id: lineItemId, quantity: 1}
-];
-
-client.checkout.updateLineItems(checkoutId, lineItems).then((checkout) => {
- console.log(checkout); // Checkout with a line item quantity updated to 1
- console.log(checkout.lineItems) // Line items on the checkout
-});
-
-Removing Line Items
-To remove line items on a checkout, use removeLineItems().
-v0:
-const lineItemId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=';
-
-cart.removeLineItem(lineItemId).then((cart) => {
- console.log(cart); // Cart with a line item removed
-});
-
-v1:
-const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID from a previous checkout.create call
-const lineItemIds = [
- 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ='
-];
-
-client.checkout.removeLineItems(checkoutId, lineItemIds).then((checkout) => {
- console.log(checkout); // Checkout with a line item removed
- console.log(checkout.lineItems) // Line items on the checkout
-});
-
-Pagination
-Most models that are part of a paginated set (products, products on collections,
-collections) are not fetched in their entirety. However, because we're using
-GraphQL, and we're compliant with the Relay specification, all of these models
-may be paginated using the underlying GraphQL Client. This functionality didn't
-really exist in a clean way under v0.
-Examples
-Paginating products on a shop.
-let productList;
-client.products.fetchAll().then((products) => {
- productList = products;
-});
-
-// Do some stuff, and later:
-
-client.fetchNextPage(productList).then((nextPageOfProducts) => {
- // Do some other stuff
-});
-
-Paginating products on within a collection.
-let productsForCollection;
-client.collection.fetchWithProducts(collectionId).then((collection) => {
- productsForCollection = collection.products;
-});
-
-// Do some stuff, and later:
-
-client.fetchNextPage(productsForCollection).then((nextPageOfProducts) => {
- // Do some other stuff
-});
-
-Paginating collections
-let collectionList;
-client.collection.fetchAll().then((collections) => {
- collectionList = collections;
-});
-
-// Do some stuff, and later:
-
-client.fetchNextPage(collectionList).then((nextPageOfCollections) => {
- // Do some other stuff
-});
-
+`;
+
+const {data, errors, extensions} = await client.request(operation);
+console.log(data.products);
+Note that with the Storefront Client, you'll be crafting GraphQL operations directly, and can therefore customize it according to your needs. Refer to the Storefront API documentation for common operations or see JS Buy SDK query equivalents.
+The JS Buy SDK uses the Checkout API (which is deprecated). With the Storefront Client, you can use the Cart API to create carts and send customers to checkout. Learn more.
+const operation = `mutation createCart($cartInput: CartInput) {
+ cartCreate(input: $cartInput) {
+ cart {
+ id
+ checkoutUrl
+ lines(first: 10) {
+ edges {
+ node {
+ id
+ merchandise {
+ ... on ProductVariant {
+ id
+ title
+ }
+ }
+ }
+ }
+ }
+ cost {
+ totalAmount {
+ amount
+ currencyCode
+ }
+ }
+ }
+ }
+}`;
+
+const {data, errors} = await client.request(operation, {
+ variables: {
+ "cartInput": {
+ "lines": [
+ {
+ "quantity": 1,
+ "merchandiseId": "gid://shopify/ProductVariant/43162292814051"
+ }
+ ]
+ }
+ }
+})
+
+console.log("Checkout URL: ", data.cartCreate.cart.checkoutUrl);
+The Storefront API limits how many items can be fetched at once. Results can be paginated using cursors. The JS Buy SDK provides helpers like fetchNextPage, Storefront API Client requires manual pagination:
const productQuery = `query Products ($numProducts: Int!, $afterCursor: String){
+ products(first: $numProducts, after: $afterCursor) {
+ nodes {
+ id
+ title
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+}`;
+
+async function paginateThroughProducts() {
+ let hasNextPage = true, afterCursor = null;
+
+ while (hasNextPage) {
+ const {
+ data: {products},
+ errors,
+ } = await client.request(productQuery, {
+ variables: {numProducts: 250, afterCursor},
+ });
+
+ products.nodes.forEach((product) => {
+ console.log(`Product ID: ${product.id}, Name: ${product.title}`);
+ // Process each product as needed
+ });
+
+ if (products.pageInfo.hasNextPage) {
+ afterCursor = products.pageInfo.endCursor;
+ } else {
+ hasNextPage = false;
+ }
+ }
+}
+
+paginateThroughProducts();
+The JS Buy SDK provides a helper method to resize images. The Storefront API client allows you to do this directly in the query instead.
+const query = `{
+ productByHandle(handle: "snowboard") {
+ id
+ thumbnail: featuredImage {
+ url(transform: {maxWidth: 100, maxHeight: 100})
+ }
+ }
+}`;
+
+const { data, errors } = await client.request(query);
+console.log(data.productByHandle.thumbnail.url);
+You may encounter network or GraphQL errors. Be prepared to handle these gracefully:
+const { data, errors } = await client.request(query)
+
+if (errors) {
+ console.error(errors.message);
+ return;
+}
+Ensure to test your new implementation thoroughly to verify that all APIs are working properly and the responses are handled correctly.
+During the migration process, it can be helpful to examine the original queries from the JS Buy SDK. We have archived these queries and their optimized versions here.
+Check out the Storefront API Client documentation to learn more.