Cart

Create, fetch, edit, or manage coupons for a customer's cart using the Unified Data Layer.

Coverage

The following table provides an overview of the methods and their coverage across different platforms.

Method	Commercetools	SAPCC	BigCommerce	SFCC	Magento
GetCart	✅	✅	✅	✅	✅
AddCartLineItem	✅	✅	✅	✅	✅
UpdateCartLineItem	✅	✅	✅	✅	✅
RemoveCartLineItem	✅	✅	✅	✅	✅
ApplyCouponToCart	✅	✅	✅	✅	✅
RemoveCouponFromCart	✅	✅	✅	✅	✅

Some of the methods that impact the cart can be found under the checkout methods. These include setCartAddress, setCustomerEmail, and setShippingMethod.

In Alokai Storefront, these functionalities are a part of either the checkout or user authentication flows.

Multi-cart support

All cart methods utilizes optional cartId argument for flexible cart object handling. In a current state, only @vsf-enterprise/unified-api-sapcc package offers full support for this feature.

Method	Commercetools	SAPCC	BigCommerce	SFCC	Magento
GetCart	❌	✅	❌	❌	❌
AddCartLineItem	❌	✅	❌	❌	❌
UpdateCartLineItem	❌	✅	❌	❌	❌
RemoveCartLineItem	❌	✅	❌	❌	❌
ApplyCouponToCart	❌	✅	❌	❌	❌
RemoveCouponFromCart	❌	✅	❌	❌	❌

getCart

The getCart method retrieves the current shopping cart and returns an SfCart object. If there is no active cart, an empty one will be created, returned, and used on future calls. If your storefront has multi-cart support, you can pass the cartId to retrieve a specific cart.

Usage

const cart = await sdk.unified.getCart();

Types

export type GetCart = (args?: GetCartArgs) => Promise<SfCart>;

export type GetCartArgs = {
  cartId?: string;
};

export interface SfCart {
  appliedCoupons: SfCartCoupon[];
  /**
   * @default null
   */
  billingAddress: Maybe<SfAddress>;
  /**
   * Active customer's email. Required to complete the checkout
   * @default null
   */
  customerEmail: Maybe<string>;
  id: SfId;
  lineItems: SfCartLineItem[];
  /**
   * Shipping address is required to get available shipping methods
   * @default null
   */
  shippingAddress: Maybe<SfAddress>;
  /**
   * Required to complete the checkout. To get available methods use `getAvailableShippingMethods`
   * @default null
   */
  shippingMethod: Maybe<SfShippingMethod>;
  /**
   * Difference of `subtotalRegularPrice` and discounts applied to line items before providing coupons.
   * If none of the products are discounted, price will be equal to `subtotalRegularPrice`
   */
  subtotalDiscountedPrice: SfMoney;
  /**
   * Total regular price of all line items (coupons, taxes, shipping excluded)
   */
  subtotalRegularPrice: SfMoney;
  totalCouponDiscounts: SfMoney;
  /**
   * Total count of all line items and their's quantities in cart
   */
  totalItems: number;
  /**
   * Total cart price (discounts, taxes, shipping included)
   */
  totalPrice: SfMoney;
  /**
   * Calculated after applying shipping method
   * @default null
   */
  totalShippingPrice: Maybe<SfMoney>;
  totalTax: SfMoney;
}

export interface SfCartLineItem {
  attributes: SfAttribute[];
  productId: SfId;
  /**
   * ID of the cart's line item
   */
  id: SfId;
  image: Maybe<SfImage>;
  name: Maybe<string>;
  quantity: number;
  sku: Maybe<string>;
  slug: string;
  /**
   * Product of quantity and unitPrice
   */
  totalPrice: Maybe<SfMoney>;
  unitPrice: Maybe<SfDiscountablePrice>;
  quantityLimit: Maybe<number>;
}

addCartLineItem

addCartLineItem adds a product to the active shopping cart. It requires the product id, and optionally the SKU and quantity. The updated SfCart object is returned. If your storefront has multi-cart support, you can pass the cartId to add a product to a specific cart.

Usage

If no quantity is provided, a quantity of 1 will be used.

// adds 1 product-id to the cart
const cart = await sdk.unified.addCartLineItem({
  productId: "product-id",
});

const cart = await sdk.unified.addCartLineItem({
  productId: "product-id",
  sku: "sku",
  quantity: 5,
});

Types

export type AddCartLineItem = (args: AddCartLineItemArgs) => Promise<SfCart>;

export interface AddCartLineItemArgs {
  productId: string;
  sku: Maybe<string>;
  quantity?: number;
  cartId?: string;
}

updateCartLineItem

updateCartLineItem modifies the quantity of a specific product in the shopping cart using that product's lineItemId. The updated SfCart object is returned. If your storefront has multi-cart support, you can pass the cartId to update a specific cart.

Usage

const cart = await sdk.unified.getCart();

// increase the first line item quantity by 1
const updatedCart = await sdk.unified.updateCartLineItem({
  lineItemId: cart.lineItems[0].id,
  quantity: cart.lineItems[0].quantity + 1,
});

Types

export interface UpdateCartLineItemArgs {
  lineItemId: string;
  quantity: number;
  cartId?: string;
}

export type UpdateCartLineItem = (args: UpdateCartLineItemArgs) => Promise<SfCart>;

removeCartLineItem

removeCartLineItem is used to remove a product from the shopping cart using a line item id. The updated SfCart object is returned. If your storefront has multi-cart support, you can pass the cartId to remove a product from a specific cart.

Usage

const cart = await sdk.unified.getCart();

// remove the first line item in the cart
const updatedCart = await sdk.unified.removeCartLineItem({
  lineItemId: cart.lineItems[0].id,
});

Types

export type RemoveCartLineItem = (args: RemoveCartLineItemArgs) => Promise<SfCart>;

export interface RemoveCartLineItemArgs {
  lineItemId: string;
  cartId?: string;
}

applyCouponToCart

applyCouponToCart lets you apply a coupon to the active cart. It requires the coupon code and returns the updated SfCart object.

Usage

To add a coupon to the active art, you can pass the coupon code as a string - this is the what a customer will enter as their coupon code. If your storefront has multi-cart support, you can pass the cartId to apply a coupon to a specific cart.

After a coupon is successfully applied to a cart, it will be visible on the cart's appliedCoupons array.

const cart = await sdk.unified.applyCouponToCart({
  couponCode: "MY-DISCOUNT-CODE",
});

console.log(cart.appliedCoupons); // [{ code: 'MY-DISCOUNT-CODE', id: 'couponId01'}]

Types

export type ApplyCouponToCart = (args: ApplyCouponToCartArgs) => Promise<SfCart>;

export interface ApplyCouponToCartArgs {
  couponCode: string;
  cartId?: string;
}

export interface SfCartCoupon {
  code: string;
  id: string;
  name: Maybe<string>;
}

removeCouponFromCart

removeCouponFromCart removes a previously applied coupon from the shopping cart using the coupon id. It returns the updated SfCart object. If your storefront has multi-cart support, you can pass the cartId to remove a coupon from a specific cart.

Usage

To remove a coupon from the cart, you can pass the couponId. This is different than the couponCode that is used in applyCouponToCart. The couponId can be accessed through the cart.appliedCoupons.

const cart = await sdk.unified.getCart();
console.log(cart.appliedCoupons); // [{ code: 'MY-DISCOUNT-CODE', id: 'couponId01'}]

const updatedCart = await sdk.unified.removeCouponFromCart({
  couponId: "couponId01",
});

console.log(updatedCart.appliedCoupons); // []

Types

export type RemoveCouponFromCart = (args: RemoveCouponFromCartArgs) => Promise<SfCart>;

export interface RemoveCouponFromCartArgs {
  /**
   * Don't confuse it with coupon code.
   */
  couponId: string;
  cartId?: string;
}

export interface SfCartCoupon {
  code: string;
  id: string;
  name: Maybe<string>;
}