addCartItem

Add an item to the cart (or update the quantity of an existing one). 🔐 This method requires authorization (or a guest context).

Description

This method adds a single item to the cart of the current context - an authorized user or a guest (resolved via the x-guest-id header, see Guest mode). If the product is already in the cart, its quantity is updated. It returns a Promise that resolves to the updated ICartResponse object.

Users.addCartItem(

body*, body.productId*, body.qty*

);

Parameters schema

Schema

body(required): ICartAddItem
Item to add. Example: { productId: 1, qty: 2 }

body.productId(required): number
Product identifier.
example: 1

body.qty(required): number
Quantity to add.
example: 2

Examples

Minimal example

const response = await Users.addCartItem({ productId: 1, qty: 2 });

Example response

{
  "items": [
    {
      "productId": 1,
      "qty": 2,
      "addedAt": "2026-05-30T10:00:00.000Z"
    }
  ],
  "total": 1
}

Response schema

Schema: ICartResponse

items: ICartItem[]
Cart items.

items.productId: number
Product identifier.
example: 1

items.qty: number
Quantity of the product in the cart.
example: 2

items.addedAt: string
ISO date when the item was added.
example: "2026-05-30T10:00:00.000Z"

total: number
Total number of items in the cart.
example: 3

---