Cart

A cart is a stateful collection of items, tied to either a cart token (guest) or a customer JWT (signed-in customer). The first call to POST /v1/store/cart/items issues a cart token; you echo it back on every subsequent cart and checkout call.

Cart object

{
  "id": "ca1b2c3d-...",
  "isGuest": true,
  "subtotal": "2980.00",
  "updatedAt": "2026-05-27T13:45:00.000Z",
  "items": [
    {
      "id": "ci1b2c3d-...",
      "productId": "f3a7...",
      "variantId": null,
      "name": "Emerald Kurti",
      "imageUrl": "https://r2.sellvik.com/products/emerald-kurti.jpg",
      "price": "1490.00",
      "quantity": 2
    }
  ]
}

Get the current cart

GET /api/v1/store/cart

Headers

X-Sellvik-Key: <publishable-key> (required)
X-Sellvik-Cart: <cart-token> (optional — guest cart)
Authorization: Bearer <customer-jwt> (optional — customer cart)

If neither cart-bound header is sent: 200 with an empty cart ({ items: [], subtotal: "0.00" }).

Add or increment an item

POST /api/v1/store/cart/items

Request body

{
  "productId": "f3a7...",
  "variantId": "v9d8...",
  "quantity": 1
}

Field	Type	Required	Notes
`productId`	uuid	yes	Product to add.
`variantId`	uuid	no	Required if the product has variants.
`quantity`	integer	yes	1–99. Increments existing line.

Response

HTTP/1.1 201 Created
X-Sellvik-Cart: eyJhbGciOiJIUzI1NiIs...

{
  "id": "ca...",
  "items": [...],
  "subtotal": "1490.00"
}

Save the X-Sellvik-Cart response header. Send it back on every subsequent cart call. If you don't, the next call creates a new cart and the items disappear from the user's perspective.

For signed-in customers (you sent a customer JWT), the cart is bound to the customer; the X-Sellvik-Cart header still works as a fallback if you lose the customer session mid-flow.

Errors

Status	Code	When
400	`invalid_body`	Missing or out-of-range fields.
404	`product_not_found`	Product doesn't exist or is inactive.
404	`variant_not_found`	Variant ID doesn't belong to the product.
409	`out_of_stock`	Requested quantity exceeds available stock.

Update item quantity (or remove)

PATCH /api/v1/store/cart/items/{itemId}

Request body

{ "quantity": 3 }

quantity: 0 removes the line.

Example

curl -X PATCH "https://api.sellvik.app/api/v1/store/cart/items/ci1b2c3d-..." \
  -H "X-Sellvik-Key: <publishable-key>" \
  -H "X-Sellvik-Cart: <cart-token>" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 3 }'

Remove an item

DELETE /api/v1/store/cart/items/{itemId}

Equivalent to PATCH ... { "quantity": 0 }. Returns 200 with the updated cart.

When a guest with a cart logs in:

Send the customer JWT on POST /v1/store/auth/login.
On the next cart call, send both X-Sellvik-Cart: <guest-token> and Authorization: Bearer <customer-jwt>.
The server merges the guest cart into the customer's cart and returns the merged result. Quantities are summed; duplicate lines are de-duped by productId + variantId.
The guest cart token is invalidated. Drop it from your client.

If the customer already had a cart with conflicting items, the merge favours the higher quantity and preserves both lines if variants differ.

On this page