shopify-buy
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/shopify-buy package

    2.12.0 • Public • Published

    Shopify JavaScript Buy SDK

    Travis

    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.

    Full API docs are available here.

    Changelog

    View our Changelog for details about our releases.

    Table Of Contents

    Installation

    With Yarn:

    $ yarn add shopify-buy

    With NPM:

    $ npm install shopify-buy

    CDN:

    There is a minified UMD build available via CDN (see the Changelog for details about the latest release):

    <script src="http://sdks.shopifycdn.com/js-buy-sdk/v2/latest/index.umd.min.js"></script>

    You can also use a specific release version:

    <script src="https://sdks.shopifycdn.com/js-buy-sdk/1.11.0/index.umd.min.js"></script>

    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 Storefront API:

    <script src="https://sdks.shopifycdn.com/js-buy-sdk/2.0.1/index.unoptimized.umd.min.js"></script>

    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 = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=';
    
    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 = 'Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzM2OTMxMjU4NA==';
    // 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);
    });

    Creating a Checkout

    // Create an empty checkout
    client.checkout.create().then((checkout) => {
      // Do something with the checkout
      console.log(checkout);
    });

    Updating checkout attributes

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9DaGVja291dC9kMTZmM2EzMDM4Yjc4N=';
    const input = {customAttributes: [{key: "MyKey", value: "MyValue"}]};
    
    client.checkout.updateAttributes(checkoutId, input).then((checkout) => {
      // Do something with the updated checkout
    });

    Adding Line Items

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID of an existing checkout
    const lineItemsToAdd = [
      {
        variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTEwNjAyMjc5Mg==',
        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
    });

    Updating Line Items

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID of an existing checkout
    const lineItemsToUpdate = [
      {id: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=', 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 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=' updated to 2
    });

    Removing Line Items

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // ID of an existing checkout
    const lineItemIdsToRemove = [
      'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ='
    ];
    
    // 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 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzc4NTc5ODkzODQ=' removed
    });

    Fetching a Checkout

    const checkoutId = '2U4NWNkYzI4ZWEyOTdlOD9rZXk9MDVjMzY3Zjk3YWM0YWJjNGRhMTkwMDgwYTUzOGJmYmI='
    
    client.checkout.fetch(checkoutId).then((checkout) => {
      // Do something with the checkout
      console.log(checkout);
    });

    Adding a Discount

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // 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);
    });

    Removing a Discount

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // 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);
    });

    Updating a Shipping Address

    const checkoutId = 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0SW1hZ2UvMTgyMTc3ODc1OTI='; // 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
    });

    Completing a checkout

    The simplest way to complete a checkout is to use the webUrl property that is returned when creating a checkout. This URL redirects the customer to Shopify's online checkout to complete the purchase.

    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);
    });

    Example Apps

    For more complete examples of using JS Buy SDK, check out our storefront-api-examples 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.

    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.

    Keywords

    none

    Install

    npm i shopify-buy

    DownloadsWeekly Downloads

    24,956

    Version

    2.12.0

    License

    MIT

    Unpacked Size

    2.95 MB

    Total Files

    27

    Last publish

    Collaborators

    • richgilbank
    • mikkoh
    • minasmart
    • tessalt
    • shopify-dep
    • swalkinshaw
    • matt888