Carts and checkout

Make and fill a cart, estimate shipping and hand it to the shop's checkout page with a single-use link.

A cart is named by its token. Make one with createCart, keep its cartToken, and reach it again with cart. The CartSession that cart returns sends the token as the X-Cart-Token header for you. Every change answers with the whole cart, with its lines, totals and coupon.

Each write takes options last: idempotencyKey, signal and headers (see retries).

Create a cart

storefront.createCart(options?: RequestOptions): Promise<Cart>

A new empty cart, named by the returned cartToken. Keep the token, in the shopper's session or a cookie, to come back to the cart. Made on a client with a shopper's access token, the cart is theirs and priced for them. Limited like cart writes (30 a minute, 300 an hour per visitor).

Parameters

Returns

The new Cart:

Errors

Example

const cart = await storefront.createCart();
localStorage.setItem('cartToken', cart.cartToken);

Open a cart

storefront.cart(cartToken: string): CartSession

A CartSession for the cart a token names. Its methods below act on that cart, and its token property holds the token.

Parameters

Returns

A CartSession. No request is made.

Example

const session = storefront.cart(cart.cartToken);

Get the cart

session.get(): Promise<Cart>

The cart as it is now, priced as the shop's own cart page prices it.

Returns

A Cart:

Errors

Example

const cart = await session.get();

Add a product

session.addItem(productId: number, quantity?: number, options?: RequestOptions): Promise<Cart>

Adds a product, or more of one already in the cart. No stock is held until the cart is claimed at checkout. Limited like cart writes.

Parameters

Returns

The changed Cart:

Errors

Example

const cart = await session.addItem(12, 2);

Change a line's quantity

session.updateItem(itemId: number, quantity: number, options?: RequestOptions): Promise<Cart>

Sets a line's quantity. A quantity of 0 removes the line. Limited like cart writes.

Parameters

Returns

The changed Cart:

Errors

Example

const updated = await session.updateItem(cart.items[0].id, 3);

Remove a line

session.removeItem(itemId: number, options?: RequestOptions): Promise<Cart>

Removes a line from the cart.

Parameters

Returns

The changed Cart:

Errors

Example

const updated = await session.removeItem(cart.items[0].id);

Apply a coupon

session.applyCoupon(code: string, options?: RequestOptions): Promise<Cart>

Checked as the shop's own cart page checks it. A coupon only a known customer can use (first order, per customer) stays on the cart for checkout to decide. Limited to 10 attempts a minute and 60 an hour per visitor.

Parameters

Returns

The changed Cart:

Errors

Example

const cart = await session.applyCoupon('WELCOME10');

Remove the coupon

session.removeCoupon(options?: RequestOptions): Promise<Cart>

Removes the cart's coupon. Removing an auto-applied coupon stops coupons auto-applying to this cart.

Parameters

Returns

The changed Cart:

Errors

Estimate shipping

session.estimateShipping(destination: ShippingDestination, options?: RequestOptions): Promise<ShippingEstimate>

The shipping rules the shopper could choose at checkout, priced for a destination as checkout prices them. Only when the shop turned its shipping calculator on (shippingEstimates from shop()). A shop without zones ships anywhere, free. Limited to 30 a minute and 300 an hour per visitor.

Parameters

Request fields

Returns

A ShippingEstimate:

Errors

Example

const estimate = await session.estimateShipping({
    shippingCountryCode: 'SAU',
    shippingCity: 'Riyadh',
});

if (estimate.shipsTo) {
    estimate.quotes.forEach((quote) => console.log(quote.name, quote.cost));
}

Get a checkout link

session.checkout(options?: CheckoutOptions, request?: RequestOptions): Promise<CheckoutLink>

A single-use link to the shop's checkout page with this cart, valid for 30 minutes, for the shopper's browser to open now. Once opened, the cart belongs to that browser and the token no longer reaches it. When requiresSignIn is true, the cart belongs to a shopper, who must be signed in on the shop. A wholesale member's cart (mode enquiry) leads to the shop's cart page, where it is sent as a quotation request. Limited like cart writes.

Parameters

Request fields

Returns

A CheckoutLink:

Errors

Example

const { checkoutUrl } = await session.checkout({
    returnPath: '/thanks',
    cartPath: '/cart',
    attribution: { utmSource: 'newsletter', utmCampaign: 'november' },
});

window.location.assign(checkoutUrl);