@nacelle/shopify-checkout v0.1.2

@nacelle/shopify-checkout

A minimal Shopify checkout client for headless storefronts.

Overview

@nacelle/shopify-checkout adds Shopify checkout functionality to headless commerce projects. While it's tailored to support the needs of Nacelle-powered storefronts, it's possible for any headless Shopify storefront to use this package by following the API described below.

Features

• tiny, with zero dependencies
• full TypeScript support
• ships in tree-shakeable ESM, as well as UMD & IIFE formats for maximum portability
• high code coverage

Usage

Install

npm i @nacelle/shopify-checkout

Prerequisites

To get started, you'll need:

• a Shopify Storefront API token with unauthenticated_read_checkouts & unauthenticated_write_checkouts access scopes
• your myshopify domain / Shop ID
  • example: for gamma-nova-jewelry.myshopify.com, the domain / Shop ID is gamma-nova-jewelry

Initializing the client

The checkout client can be initialized anywhere in your application. We recommend initializing it once. You can then import the initialized client wherever it's needed.

import createShopifyCheckoutClient from '@nacelle/shopify-checkout';

const checkoutClient = createShopifyCheckoutClient({
  storefrontCheckoutToken: '<your-storefront-api-token>',
  myshopifyDomain: '<your-shop-id>'
});

Common Types

When working with the checkout client, there are some common types that it will help to be familiar with:

Examples of Common Types:

Metafield

{ key: 'forecast', value: 'sunshine' }

CartItem

{
  variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8xMjM0NQ==',
  quantity: 4
},
{
  variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC85ODc2NQ==',
  quantity: 2,
  metafields: [
    { key: 'care_instructions', value: 'hand wash; drip dry' }
  ]
},

Checkout client API

The checkout client exposes two methods, get and process.

get({ id })

Retrieves an existing Shopify checkout.

Accepts: params - an object containing the id (string) of interest.

Returns: a ShopifyCheckout.

Example

const id = 'Z2lkOi8vc2hvcGlmeS9DaGVja291dC85OTg4Nzc/a2V5PTEyMzEyMw==';
const checkout = await checkoutClient.get({ id });

process(params)

Creates a new Shopify checkout, or updates an existing Shopify checkout.

Accepts: params (see examples below).

Returns: a ShopifyCheckout.

Creating a new Shopify checkout

Example

// create a new checkout with checkout-level `customAttributes` and `note`
const checkout = await checkoutClient.process({
  cartItems: [
    {
      variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8xMjM0NQ==',
      quantity: 1
    }
  ],
  metafields: [{ key: 'gift_options', value: 'wrapped in gift paper' }],
  note: 'Thanks for taking care of the gift wrapping!'
});

Updating an existing Shopify checkout

Example

// Update an existing checkout's line items, `customAttributes`, and `note`
const checkout = await checkoutClient.process({
  id: 'Z2lkOi8vc2hvcGlmeS9DaGVja291dC85OTg4Nzc/a2V5PTEyMzEyMw==',
  cartItems: [
    {
      variantId: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8xMjM0NQ==',
      quantity: 1,
      metafields: [{ key: 'engrave_text', value: 'i ❤️ headless commerce' }]
    }
  ],
  metafields: [{ key: 'gift_options', value: 'in box with bow' }],
  note: 'Please use a red ribbon for the bow, if possible :)'
});

Applying a discount to checkout

Example

// Apply a discount code to checkout
const checkout = await checkoutClient.discountApply({
  id: 'Z2lkOi8vc2hvcGlmeS9DaGVja291dC85OTg4Nzc/a2V5PTEyMzEyMw==',
  discountCode: 'BFCM'
});

Removing a discount from checkout

Example

// Remove discount code from checkout
const checkout = await checkoutClient.discountRemove({
  id: 'Z2lkOi8vc2hvcGlmeS9DaGVja291dC85OTg4Nzc/a2V5PTEyMzEyMw=='
});

Making custom checkout queries to the Shopify Storefront API

Example

// Send any query/mutation to the Shopify Storefront API
const checkout = await checkoutClient.query({
  query: `
    mutation checkoutShippingAddressUpdateV2($checkoutId: ID!, $shippingAddress: MailingAddressInput!) {
      checkoutShippingAddressUpdateV2(checkoutId: $checkoutId, shippingAddress: $shippingAddress) {
        checkout {
          id
          webUrl
        }
        checkoutUserErrors {
          code
          fields
          message
        }
      }
    }
    `,
  variables: {
    checkoutId: checkoutData.id,
    shippingAddress: {
      address1: '123 smith street',
      city: 'Smith',
      country: 'USA',
      firstName: 'John',
      lastName: 'John'
    }
  }
});

Other example mutations from Shopify docs:

• checkoutShippingAddressUpdateV2
• checkoutCustomerAssociateV2

Advanced Usage

Using a custom fetchClient

By default, @nacelle/shopify-checkout makes GraphQL requests to Shopify's Storefront API with window.fetch. If window.fetch doesn't meet your project's requirements (e.g. if you need to support IE11), you can supply a fetchClient when initializing the checkout client. For example:

import createShopifyCheckoutClient from '@nacelle/shopify-checkout';
import isoFetch from 'isomorphic-unfetch';

const checkoutClient = createShopifyCheckoutClient({
  storefrontCheckoutToken: '<your-storefront-api-token>',
  myshopifyDomain: '<your-shop-id>',
  fetchClient: isoFetch
});

The only requirement of the fetchClient is that it implements the Fetch API (axios, for instance, won't work). We recommend checking out isomorphic-unfetch, cross-fetch, or similar.

Using a custom Shopify endpoint

If you'd prefer to specify a Shopify Storefront GraphQL API endpoint directly, without supplying a myshopifyDomain, you may do so by specifying a customEndpoint when initializing the checkout client. For example:

const checkoutClient = createShopifyCheckoutClient({
  storefrontCheckoutToken: '<your-storefront-api-token>',
  customEndpoint: '<your-storefront-api-endpoint>'
});