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;
};

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

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();