@nacelle/shopify-cart

A Shopify Cart client for Nacelle-powered headless storefronts.

Features

• Zero dependencies
• Full TypeScript support
• Ships in ESM, UMD & IIFE formats for maximum portability
• 100% code coverage

Versioning

Per the Project Roadmap below, @nacelle/shopify-cart will release quarterly updates that coincide with the Shopify Storefront API's release schedule, such that the @latest version of @nacelle/shopify-cart uses the latest version of the Shopify Storefront API. Features in the Project Roadmap will be added in quarterly releases. Minor updates & patches will be released on an as-needed basis.

Project Roadmap

We welcome feature & enhancement suggestions via GitHub Issues.

January 2023

• Update to use the 2023-01 version of the Shopify Storefront API.

April 2023

• Update to use the 2023-04 version of the Shopify Storefront API.

Usage

Install

npm i @nacelle/shopify-cart

Prerequisites

To get started, you'll need:

• A Shopify Storefront API access token with unauthenticated_read_checkouts & unauthenticated_write_checkouts access scopes
  • If you need access to Selling Plans data, you must also enable the unauthenticated_read_selling_plans access scope
• Your Shop ID (myshopify domain)
  • Example: for gamma-nova-jewelry.myshopify.com, the Shop ID is gamma-nova-jewelry

Initializing the client

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

The cart client accepts the following parameters:

• shopifyShopId (string) - optional Shopify shop id
• shopifyStorefrontAccessToken (string) - required Shopify Storefront API access token
• shopifyCustomEndpoint (string) - optional Shopify custom API endpoint
• customFragments (object) - optional GraphQL fragments for data customization (see the Custom Fragments docs)
• fetchClient (function) - optional Fetch API-compatible request function
• country (string) - optional Shopify Country Code used for cart queries/responses. Defaults to ZZ (unknown region) if not supplied.
• language (string) - optional Shopify Language Code used for cart queries/responses. Defaults to EN if not supplied.
• locale (string) - optional Nacelle locale used to assign NacelleCartMerchandise the correct nacelleEntryId. Defaults to en-US if not supplied.

You must provide a shopifyShopId or a shopifyCustomEndpoint

Example

import createShopifyCartClient from '@nacelle/shopify-cart';

const cartClient = createShopifyCartClient({
  shopifyShopId: '<your-shop-id>',
  shopifyStorefrontAccessToken: '<your-shopify-storefront-api-access-token>'
});

Querying additional fields with custom GraphQL fragments

If you'd like to query for additional fields on the Cart object or its sub-properties, please see the Custom Fragments docs to learn how to supply customFragments to the cartClient.

Response Data

Every method on the cartClient returns an object with the following keys.

1. cart - a Nacelle-oriented Shopify cart object. The cart matches the Shopify Cart object, with one exception: cart.lines[idx].merchandise contains a nacelleEntryId, and its id is renamed to sourceEntryId. This more closely aligns your cart data with the commerce data in your Nacelle-powered headless storefront.
2. userErrors - an array of Shopify CartUserError objects.
3. errors - an array of top-level Shopify API Errors

Types

For projects using typescript, types are exported along with the client & client methods.

Available types:

1. NacelleCartInput - cartCreate params
2. NacelleCartLineItemInput - cartLinesAdd params
3. NacelleCartLineItemUpdateInput - cartLinesUpdate params
4. AttributeInput - cartAttributesUpdate params
5. CartBuyerIdentityInput - cartBuyerIdentityUpdate params
6. Cart - Shopify cart object
7. ShopifyError - Shopify error response
8. CartResponse - response on cart requests
9. CartUserError - Shopify user error response on cart requests

Example

import createShopifyCartClient from '@nacelle/shopify-cart';
import type { NacelleCartInput, CartResponse } from '@nacelle/shopify-cart';

const cartClient = createShopifyCartClient({
  shopifyShopId: '<your-shop-id>',
  shopifyStorefrontAccessToken: '<your-shopify-storefront-api-access-token>'
});
const lines: NacelleCartInput[] = [
  {
    quantity: 1,
    nacelleEntryId: '<nacelle-entry-id>'
  }
];
const response: CartResponse = await cartClient.cartCreate({ lines });

Cart client API

The cart client exposes the following methods:

• cart
• cartAttributesUpdate
• cartBuyerIdentityUpdate
• cartCreate
• cartDiscountCodesUpdate
• cartLinesAdd
• cartLinesRemove
• cartLinesUpdate
• cartNoteUpdate
• getConfig
• setConfig

cart({ cartId })

Retrieves an existing Shopify cart.

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

Example

const { cart, userErrors, errors } = await cartClient.cart({
  cartId: 'gid://shopify/Cart/112233'
});

cartAttributesUpdate({ cartId, attributes })

Updates an existing Shopify cart's attributes.

Accepts: params - an object containing the cartId (string) of interest, and the attributes (array) to set. For more information on the cart attributes, checkout Shopify's AttributeInput

Example

const { cart, userErrors, errors } = await cartClient.cartAttributesUpdate({
  cartId: 'gid://shopify/Cart/112233',
  attributes: [{ key: 'gift_options', value: 'in box with bow' }]
});

cartBuyerIdentityUpdate({ cartId, buyerIdentity })

Updates an existing Shopify cart's buyer identity.

Accepts: params - an object containing the cartId (string) of interest, and the buyerIdentity (object) to set. For more information on the cart buyerIndentity, checkout Shopify's CartBuyerIdentityInput

Example

const { cart, userErrors, errors } = await cartClient.cartBuyerIdentityUpdate({
  cartId: 'gid://shopify/Cart/112233',
  buyerIdentity: { email: 'email@example.com' }
});

cartCreate(cartInput)

Creates a new Shopify cart.

Accepts: params - an optional object containing the following optional values: attributes (array), buyerIdentity (object), discountCodes (array), lines (array), note (string). To initialize an empty cart, exclude all parameters. For more information on the cart optional values, checkout Shopify's CartInput. Note that the lines parameter differs from Shopify CartLineInput in that it expects the variant's nacelleEntryId instead of a Shopify merchandiseId.

Example

const { cart, userErrors, errors } = await cartClient.cartCreate({
  lines: [
    {
      nacelleEntryId: '<nacelle-entry-id>',
      quantity: 1
    }
  ],
  attributes: [{ key: 'gift_options', value: 'in box with bow' }],
  note: 'Please use a red ribbon for the bow, if possible :)'
});

cartDiscountCodesUpdate({ cartId, discountCodes })

Updates an existing Shopify cart's discount codes.

Accepts: params - an object containing the cartId (string) of interest, and the discountCodes (array) to set.

Example

const { cart, userErrors, errors } = await cartClient.cartDiscountCodesUpdate({
  cartId: 'gid://shopify/Cart/112233',
  discountCodes: ['20OFF']
});

cartLinesAdd({ cartId, lines })

Adds lines to an existing Shopify cart.

Accepts: params - an object containing the cartId (string) of interest, and the lines (array) to add. For more information on the cart lines, checkout Shopify's CartLineInput. Note that the lines parameter differs from Shopify CartLineInput in that it expects the variant's nacelleEntryId instead of a Shopify merchandiseId.

Example

const { cart, userErrors, errors } = await cartClient.cartLinesAdd({
  cartId: 'gid://shopify/Cart/112233',
  lines: [
    {
      nacelleEntryId: '<nacelle-entry-id>',
      quantity: 1
    }
  ]
});

cartLinesRemove({ cartId, lineIds })

Removes lines from an existing Shopify cart.

Accepts: params - an object containing the cartId (string) of interest, and the lineIds (array) to remove.

Example

const { cart, userErrors, errors } = await cartClient.cartLinesRemove({
  cartId: 'gid://shopify/Cart/112233',
  lineIds: [
    'gid://shopify/CartLine/e543caf96fa645b54d07ab2035ef9dba?cart=a7aad2fb1e6611422c946f6827710550'
  ]
});

cartLinesUpdate({ cartId, lines })

Updates lines on an existing Shopify cart.

Accepts: params - an object containing the cartId (string) of interest, and the lines (array) to update. For more information on the cart lines, checkout Shopify's CartLineUpdateInput. Note that the lines parameter differs from Shopify CartLineInput in that it expects the variant's nacelleEntryId instead of a Shopify merchandiseId.

Example

const { cart, userErrors, errors } = await cartClient.cartLinesUpdate({
  cartId: 'gid://shopify/Cart/112233',
  lines: [
    {
      id: 'gid://shopify/CartLine/e543caf96fa645b54d07ab2035ef9dba?cart=a7aad2fb1e6611422c946f6827710550'
      nacelleEntryId: '<nacelle-entry-id>',
      quantity: 3
    }
  ]
});

cartNoteUpdate({ cartId, note })

Updates note on an existing Shopify cart.

Accepts: params - an object containing the cartId (string) of interest, and the note (string) to update.

Example

const { cart, userErrors, errors } = await cartClient.cartNoteUpdate({
  cartId: 'gid://shopify/Cart/112233',
  note: 'Please use a red ribbon for the bow, if possible :)'
});

getConfig()

Gets language and country values used to make requests to Shopify.

setConfig({language, country})

Updates the language and country settings used to make requests to Shopify.

Accepts: config - an object containing optional values for the language (string) and country (string). These values should be a LanguageCode and CountryCode respectively.

setConfig Example

// update the language
cartClient.setConfig({ language: 'FR' });

// update country
cartClient.setConfig({ country: 'CA' });

// update the language & country
cartClient.setConfig({ country: 'CA', language: 'FR' });