CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>JSDoc: Home</title> <script src="scripts/prettify/prettify.js"> </script> <script src="scripts/prettify/lang-css.js"> </script>  <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> <style> /* Hide the deprecation notice on the home page so we don't double up */ body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) { display: none; } /* Tidy headings */ section h1 { margin-left: 0; } #deprecation-notice { background-color: #fff9e3; border: 1px solid #ff9900; border-radius: 5px; color: #333; margin: 20px; padding: 10px 20px; font-family: Arial; } </style> </head> <body class="home"> <div id="main"> <div id="deprecation-notice"> <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>. </div> <section> <article> <h1 id="shopify-javascript-buy-sdk">Shopify JavaScript Buy SDK</h1> <p>The JS Buy SDK is a lightweight library that allows you to build ecommerce into any website. It's based on Shopify's <a href="https://help.shopify.com/api/storefront-api/getting-started">Storefront API</a> and provides the ability to retrieve products and collections from your shop, add products to a cart, and checkout.</p> <p><a href="https://help.shopify.com/en/api/storefront-api/reference">Full API docs are available here</a>.</p> <h2 id="changelog">Changelog</h2> <p>View our <a href="https://github.com/Shopify/js-buy-sdk/blob/main/CHANGELOG.md">Changelog</a> for details about our releases.</p> <h2 id="sdk-version-support">SDK Version Support</h2> <p>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 <a href="https://shopify.dev/docs/api/usage/versioning">here</a>.</p> <h2 id="table-of-contents">Table Of Contents</h2> <ul> <li><a href="#installation">Installation</a></li> <li><a href="#builds">Builds</a></li> <li><a href="#examples">Examples</a> <ul> <li><a href="#initializing-the-client">Initializing the Client</a></li> <li><a href="#fetching-products">Fetching Products</a></li> <li><a href="#fetching-collections">Fetching Collections</a></li> <li><a href="#creating-a-checkout">Creating a Checkout</a></li> <li><a href="#updating-checkout-attributes">Updating Checkout Attributes</a></li> <li><a href="#adding-line-items">Adding Line Items</a></li> <li><a href="#updating-line-items">Updating Line Items</a></li> <li><a href="#removing-line-items">Removing Line Items</a></li> <li><a href="#fetching-a-checkout">Fetching a Checkout</a></li> <li><a href="#adding-a-discount">Adding a Discount</a></li> <li><a href="#removing-a-discount">Removing a Discount</a></li> <li><a href="#updating-a-shipping-address">Updating a Shipping Address</a></li> <li><a href="#completing-a-checkout">Completing a checkout</a></li> </ul> </li> <li><a href="#expanding-the-sdk">Expanding the SDK</a> <ul> <li><a href="#initializing-the-client-1">Initializing the Client</a></li> <li><a href="#fetching-products-1">Fetching Products</a></li> </ul> </li> <li><a href="#example-apps">Example Apps</a></li> <li><a href="#documentation">Documentation</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#code-of-conduct">Code of Conduct</a></li> <li><a href="#license">License</a></li> </ul> <h2 id="installation">Installation</h2> <p><strong>With Yarn:</strong></p> <pre class="prettyprint source lang-bash"><code>$ yarn add shopify-buy </code></pre> <p><strong>With NPM:</strong></p> <pre class="prettyprint source lang-bash"><code>$ npm install shopify-buy </code></pre> <p><strong>CDN:</strong></p> <p>There is a minified UMD build of the latest release available via CDN (see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/CHANGELOG.md">Changelog</a> for details about the latest release):</p> <pre class="prettyprint source lang-html"><code><script src="https://sdks.shopifycdn.com/js-buy-sdk/v2/latest/index.umd.min.js"></script> </code></pre> <p>If you <strong>don't</strong> want to use the latest version, you can use a specific older release version:</p> <pre class="prettyprint source lang-html"><code><script src="https://sdks.shopifycdn.com/js-buy-sdk/1.11.0/index.umd.min.js"></script> </code></pre> <p>You can also fetch the unoptimized release for a version (2.0.1 and above). This will be larger than the optimized version, as it will contain all fields that are available in the <a href="https://help.shopify.com/en/api/custom-storefronts/storefront-api/reference">Storefront API</a>:</p> <pre class="prettyprint source lang-html"><code><script src="https://sdks.shopifycdn.com/js-buy-sdk/2.0.1/index.unoptimized.umd.min.js"></script> </code></pre> <h2 id="builds">Builds</h2> <p>The JS Buy SDK has four build versions: ES, CommonJS, AMD, and UMD.</p> <p><strong>ES, CommonJS:</strong></p> <pre class="prettyprint source lang-javascript"><code>import Client from 'shopify-buy'; </code></pre> <p><strong>AMD:</strong></p> <pre class="prettyprint source lang-javascript"><code>import Client from 'shopify-buy/index.amd'; </code></pre> <p><strong>UMD:</strong></p> <pre class="prettyprint source lang-javascript"><code>import Client from 'shopify-buy/index.umd'; </code></pre> <p><strong>UMD Unoptimized:</strong> This will be larger than the optimized version, as it will contain all fields that are available in the <a href="https://help.shopify.com/en/api/custom-storefronts/storefront-api/reference">Storefront API</a>. This should only be used when you need to add custom queries to supplement the JS Buy SDK queries.</p> <pre class="prettyprint source lang-javascript"><code>import Client from 'shopify-buy/index.unoptimized.umd'; </code></pre> <h2 id="examples">Examples</h2> <h3 id="initializing-the-client">Initializing the Client</h3> <p>If your store supports multiple languages, Storefront API can return translated resource types and fields. Learn more about <a href="https://help.shopify.com/en/api/guides/multi-language/translating-content-api">translating content</a>.</p> <pre class="prettyprint source lang-javascript"><code>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' }); </code></pre> <h3 id="fetching-products">Fetching Products</h3> <pre class="prettyprint source lang-javascript"><code>// 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); }); </code></pre> <h3 id="fetching-collections">Fetching Collections</h3> <pre class="prettyprint source lang-javascript"><code>// 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); }); </code></pre> <h3 id="creating-a-checkout">Creating a Checkout</h3> <pre class="prettyprint source lang-javascript"><code>// Create an empty checkout client.checkout.create().then((checkout) => { // Do something with the checkout console.log(checkout); }); </code></pre> <h3 id="updating-checkout-attributes">Updating checkout attributes</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; const input = {customAttributes: [{key: "MyKey", value: "MyValue"}]}; client.checkout.updateAttributes(checkoutId, input).then((checkout) => { // Do something with the updated checkout }); </code></pre> <h3 id="adding-line-items">Adding Line Items</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout const lineItemsToAdd = [ { variantId: 'gid://shopify/ProductVariant/29106064584', quantity: 5, customAttributes: [{key: "MyKey", value: "MyValue"}] } ]; // Add an item to the checkout client.checkout.addLineItems(checkoutId, lineItemsToAdd).then((checkout) => { // Do something with the updated checkout console.log(checkout.lineItems); // Array with one additional line item }); </code></pre> <h3 id="updating-line-items">Updating Line Items</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout const lineItemsToUpdate = [ {id: 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef', quantity: 2} ]; // Update the line item on the checkout (change the quantity or variant) client.checkout.updateLineItems(checkoutId, lineItemsToUpdate).then((checkout) => { // Do something with the updated checkout console.log(checkout.lineItems); // Quantity of line item 'gid://shopify/Product/7857989384' updated to 2 }); </code></pre> <h3 id="removing-line-items">Removing Line Items</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout const lineItemIdsToRemove = [ 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef' ]; // Remove an item from the checkout client.checkout.removeLineItems(checkoutId, lineItemIdsToRemove).then((checkout) => { // Do something with the updated checkout console.log(checkout.lineItems); // Checkout with line item 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef' removed }); </code></pre> <h3 id="fetching-a-checkout">Fetching a Checkout</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8' client.checkout.fetch(checkoutId).then((checkout) => { // Do something with the checkout console.log(checkout); }); </code></pre> <h3 id="adding-a-discount">Adding a Discount</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout const discountCode = 'best-discount-ever'; // Add a discount code to the checkout client.checkout.addDiscount(checkoutId, discountCode).then(checkout => { // Do something with the updated checkout console.log(checkout); }); </code></pre> <h3 id="removing-a-discount">Removing a Discount</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout // Removes the applied discount from an existing checkout. client.checkout.removeDiscount(checkoutId).then(checkout => { // Do something with the updated checkout console.log(checkout); }); </code></pre> <h3 id="updating-a-shipping-address">Updating a Shipping Address</h3> <pre class="prettyprint source lang-javascript"><code>const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout const shippingAddress = { address1: 'Chestnut Street 92', address2: 'Apartment 2', city: 'Louisville', company: null, country: 'United States', firstName: 'Bob', lastName: 'Norman', phone: '555-625-1199', province: 'Kentucky', zip: '40202' }; // Update the shipping address for an existing checkout. client.checkout.updateShippingAddress(checkoutId, shippingAddress).then(checkout => { // Do something with the updated checkout }); </code></pre> <h3 id="completing-a-checkout">Completing a checkout</h3> <p>The simplest way to complete a checkout is to use the <a href="https://help.shopify.com/en/api/storefront-api/reference/object/checkout">webUrl</a> property that is returned when creating a checkout. This URL redirects the customer to Shopify's <a href="https://help.shopify.com/en/manual/checkout-settings">online checkout</a> to complete the purchase.</p> <h2 id="expanding-the-sdk">Expanding the SDK</h2> <p>Not all fields that are available on the <a href="https://help.shopify.com/en/api/custom-storefronts/storefront-api/reference">Storefront API</a> 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.</p> <h3 id="initializing-the-client-2">Initializing the Client</h3> <pre class="prettyprint source lang-javascript"><code>// 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' }); </code></pre> <h3 id="fetching-products-2">Fetching Products</h3> <pre class="prettyprint source lang-javascript"><code>// 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); }); </code></pre> <h2 id="example-apps">Example Apps</h2> <p>For more complete examples of using JS Buy SDK, check out our <a href="https://github.com/Shopify/storefront-api-examples">storefront-api-examples</a> project. There are JS Buy SDK specific example apps in Node, Ember, and React. You can use these examples as a guideline for creating your own custom storefront.</p> <h2 id="documentation">Documentation</h2> <ul> <li><a href="https://help.shopify.com/en/api/storefront-api/tools/js-buy-sdk/getting-started">Getting started guide</a></li> <li><a href="https://shopify.github.io/js-buy-sdk">API documentation</a>.</li> </ul> <h2 id="contributing">Contributing</h2> <p>For help on setting up the repo locally, building, testing, and contributing please see <a href="https://github.com/Shopify/js-buy-sdk/blob/main/CONTRIBUTING.md">CONTRIBUTING.md</a>.</p> <h2 id="code-of-conduct">Code of Conduct</h2> <p>All developers who wish to contribute through code or issues, take a look at the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/CODE_OF_CONDUCT.md">CODE_OF_CONDUCT.md</a>.</p> <h2 id="license">License</h2> <p>MIT, see <a href="https://github.com/Shopify/js-buy-sdk/blob/main/LICENSE.txt">LICENSE.md</a> for details.</p> <img src="https://cdn.shopify.com/shopify-marketing_assets/builds/19.0.0/shopify-full-color-black.svg" width="200" /> </article> </section> </div> <nav> <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul> </nav> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time) </footer> <script> prettyPrint(); </script> <script src="scripts/linenumber.js"> </script> </body> </html>