Cart & wishlist

The cart is tied to the session cookie (see Overview). Guests get a cart keyed to their session; once a customer logs in, the cart is keyed to their account. Always send credentials: "include" so the cart persists across requests.

When a guest logs in, call POST /storefront/cart/merge to fold their guest cart into their account cart.

Endpoints

GET/storefront/cartGet the cart

Returns the current session's cart with product and variant details (including images).

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": 91,
        "product_id": 412,
        "variant_id": null,
        "quantity": 2,
        "product": { "id": 412, "name": "Trail Runner Edition 02", "slug": "...", "price": "96.00", "sale_price": "79.00", "images": [{ "url": "https://..." }] },
        "variant": null
      }
    ]
  }
}

If there is no session, items is an empty array.

POST/storefront/cartAdd an item

Adds a product (and optional variant) to the cart. If the line already exists, its quantity is increased.

curl -X POST "https://your-store-api.example.com/api/v1/storefront/cart" \
  -H "Content-Type: application/json" \
  --cookie-jar cookies.txt --cookie cookies.txt \
  -d '{ "product_id": 412, "quantity": 1 }'

Returns the created/updated cart line under data.item.

PUT/storefront/cart/:idUpdate quantity

Sets the quantity of a cart line (must be >= 1). :id is the cart line id returned by GET /storefront/cart.

{ "quantity": 3 }

DELETE/storefront/cart/:idRemove a line

Removes a single cart line.

{ "status": "success", "message": "Item removed from cart" }

DELETE/storefront/cartClear the cart

Removes every line from the current session's cart.

POST/storefront/cart/mergeMerge a guest cart on login

Requires a logged-in session. Call this right after login: it merges the guest session's cart into the customer's cart (summing quantities for matching lines), then clears the guest copy.

{ "status": "success", "message": "Cart merged successfully" }

POST/storefront/cart/validate-branch-stockValidate stock for a branch

Only relevant when the branches addon is on. Given a branch_id and cart lines, returns which lines are unavailable at that branch so you can prompt the shopper before checkout.

{
  "status": "success",
  "data": {
    "unavailable_line_ids": [91],
    "unavailable_items": [{ "product_id": 412, "variant_id": null, "name": "Trail Runner Edition 02" }]
  }
}