@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
- If you need access to Selling Plans data, you must also enable the
- Your Shop ID (
myshopify
domain)- Example: for
gamma-nova-jewelry.myshopify.com
, the Shop ID isgamma-nova-jewelry
- Example: for
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 toZZ
(unknown region) if not supplied. -
language
(string
) - optional Shopify Language Code used for cart queries/responses. Defaults toEN
if not supplied. -
locale
(string
) - optional Nacellelocale
used to assignNacelleCartMerchandise
the correctnacelleEntryId
. Defaults toen-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.
-
cart
- a Nacelle-oriented Shopify cart object. Thecart
matches the ShopifyCart
object, with one exception:cart.lines[idx].merchandise
contains anacelleEntryId
, and itsid
is renamed tosourceEntryId
. This more closely aligns yourcart
data with the commerce data in your Nacelle-powered headless storefront. -
userErrors
- an array of ShopifyCartUserError
objects. -
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:
-
NacelleCartInput
-cartCreate
params -
NacelleCartLineItemInput
-cartLinesAdd
params -
NacelleCartLineItemUpdateInput
-cartLinesUpdate
params -
AttributeInput
-cartAttributesUpdate
params -
CartBuyerIdentityInput
-cartBuyerIdentityUpdate
params -
Cart
- Shopify cart object -
ShopifyError
- Shopify error response -
CartResponse
- response on cart requests -
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' });