Cart Items

Overview

The CartService provides stateless methods for managing items in a cart. Every method takes a cartId as the first argument and returns the full updated CartType.

Types

@geins/types

type CartItemInputType = {
  skuId?: number;
  id?: string;
  groupKey?: string;
  quantity: number;
  message?: string;
};

type CartItemType = {
  id?: string;
  groupKey?: string;
  type?: ItemType;
  title?: string;
  product?: ProductType;
  skuId?: number;
  quantity: number;
  campaign?: CampaignType;
  productPackage?: ProductPackageCartItemType;
  productPackageCartItems?: CartItemType[];
  message?: string;
  totalPrice?: PriceType;
  unitPrice?: PriceType;
  configurationId?: string;
  configuration?: CartItemConfigurationType;
};

declare enum ItemType {
  PRODUCT = 'PRODUCT',
  PACKAGE = 'PACKAGE',
}

A line added from a committed configuration carries the configuration's id and a summary of it, see Configuration (CPQ). Its configuration also carries committedConfigurationId, articleNumber, discountPercent and weightPerUnit, each absent where the API answers none. On a line added before the API copied configurations onto lines, configuration is absent while configurationId is set.

Each image in product.productImages carries its fileName and url, the asset library URL. url is null for an image outside the library, which is served by its fileName as before.

Identifying Items

Each item in the cart has a unique id generated by the system. You can target items by id or skuId.

Adding Items

Add an item using addItem. If a cart doesn't exist yet, create one first.

// Create a cart first
const cart = await geinsOMS.cart.create();

// Add item by skuId
const updatedCart = await geinsOMS.cart.addItem(cart.id, {
  skuId: 1234,
  quantity: 1,
});

With Quantity and Message

// Add 2 units
const cart = await geinsOMS.cart.addItem(cartId, {
  skuId: 1234,
  quantity: 2,
});

// Add with a message
const cart = await geinsOMS.cart.addItem(cartId, {
  skuId: 1234,
  quantity: 1,
  message: 'Gift wrapping please',
});

INFO

The Geins API treats items with the same skuId but different message as separate line items. Items with the same skuId and message will have their quantities combined.

Package / Bundle

Adding a product package uses addPackageItem:

const cart = await geinsOMS.cart.addPackageItem(cartId, 1234, [
  { groupId: 1, optionId: 19, skuId: 1329 },
  { groupId: 2, optionId: 2, skuId: 1325 },
  { groupId: 3, optionId: 4, skuId: 1342 },
]);

WARNING

addPackageItem will throw an error if the selections are not valid. Make sure to handle errors.

Updating Items

Set an item to an exact quantity using updateItem:

// Set quantity to 3
const cart = await geinsOMS.cart.updateItem(cartId, {
  skuId: 1234,
  quantity: 3,
});

// Update message
const cart = await geinsOMS.cart.updateItem(cartId, {
  id: 'item-id-123',
  quantity: 1,
  message: 'New message',
});

Deleting Items

Remove an item entirely using deleteItem:

const cart = await geinsOMS.cart.deleteItem(cartId, 'item-id-123');

Or set quantity to 0 with updateItem:

const cart = await geinsOMS.cart.updateItem(cartId, {
  skuId: 1234,
  quantity: 0,
});

Session Layer Convenience

The CartSession provides higher-level convenience methods on top of the stateless core:

import { CartSession } from '@geins/oms';
const session = new CartSession(geinsOMS.cart, locale);
await session.get(); // load or create cart

// Add — increments quantity if item already exists
await session.items.add({ skuId: 1234 });

// Remove — decrements quantity, deletes if 0
await session.items.remove({ skuId: 1234 });

// Update — sets exact quantity
await session.items.update({ skuId: 1234, quantity: 5 });

// Delete — removes item entirely
await session.items.delete({ id: 'item-id-123' });

// Clear all items
await session.items.clear();

// Get cached items
const items = session.items.get();