# cart (https://docs.salla.dev/twilight/react/sdk/cart)



Use `Salla.cart` for everything the customer does to the cart in the browser. To show a cart on a page, read it with the [`cart` API module](https://docs.salla.dev/twilight/react/api/modules/cart) or the [cart route](https://docs.salla.dev/twilight/react/routes/cart).

```tsx title="app/components/product/QuantityAdd.tsx"
export function QuantityAdd({ productId }: { productId: number }) {
  async function add(quantity: number) {
    await window.salla?.cart.addItem({ id: productId, quantity, notes: 'Gift wrap please' });
  }
  return <button onClick={() => add(2)}>Add two</button>;
}
```

You never pass a cart id. The SDK finds the customer's current cart, and creates one on the first add.

## Items [#items]

| Method        | Parameters                                    | Does                                                              |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| `addItem`     | `id` or `{ id, quantity?, options?, notes? }` | Adds a product. Without `quantity` it uses the quick-add request. |
| `quickAdd`    | `id, quantity?`                               | Adds a product from a list, without opening its page              |
| `updateItem`  | `{ id, quantity?, options? }` or `FormData`   | Changes a cart item. `id` is the **cart item** id.                |
| `deleteItem`  | `itemId` or `{ id }`                          | Removes a cart item                                               |
| `deleteImage` | `fileId` or `{ id }`                          | Removes an image the customer uploaded for an item                |

`options` maps each option id to the chosen value: the value id for a choice, a URL for an uploaded image, or the text for a text field.

```ts
Salla.cart.addItem({
  id: 1234,
  quantity: 1,
  options: { 117414452: 11232214, 117411132: 'Name on the cup' },
});
```

## Coupons [#coupons]

| Method         | Parameters             | Does                                                                                         |
| -------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
| `addCoupon`    | `code` or `{ coupon }` | Applies a coupon                                                                             |
| `deleteCoupon` | `code?`                | Removes the coupon. On a store that allows several, pass the `code` to remove only that one. |

The [`useCoupon`](https://docs.salla.dev/twilight/react/hooks/use-coupon) hook wraps both, with loading and error state.

## Read the cart [#read-the-cart]

| Method                   | Parameters       | Returns                                                                                 |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------- |
| `details`                | `cartId?, with?` | The cart with its items. `with` can be `['options', 'attachments']` for more item data. |
| `getCurrentCartId`       | none             | A promise of the current cart id                                                        |
| `latest`                 | none             | The customer's latest cart, created if there is none                                    |
| `status`                 | `cartId?`        | Whether the cart is active and its next step (`checkout`, `login` or `refresh`)         |
| `offers`                 | none             | The offers that apply to the cart                                                       |
| `getUploadImageEndpoint` | `cartId?`        | The URL to upload an item image to. A string, not a request.                            |

## Checkout and quick order [#checkout-and-quick-order]

| Method                  | Parameters                                                      | Does                                                                           |
| ----------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `submit`                | none                                                            | Sends the customer on: to checkout, or to log in first when the store needs it |
| `getQuickOrderSettings` | none                                                            | Reads the store's quick-order form settings                                    |
| `createQuickOrder`      | `{ name, email?, phone, country_code, product_ids, agreement }` | Places an order without the usual checkout steps                               |
| `priceQuote`            | `cartId?`                                                       | Asks the store for a price quote. A guest is asked to log in first.            |
| `reset`                 | none                                                            | Forgets the saved cart in the browser, so the next call loads a fresh one      |

## Events [#events]

| Event                                                      | Fires when                           | Arguments                                                             |
| ---------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------- |
| `cart::updated`                                            | The cart changed by any method above | the cart summary (`count`, `total`, `sub_total`, `discount` and more) |
| `cart::before.add.item`                                    | Before an add is sent                | `{ id, payload }`, which you can change                               |
| `cart::item.added` / `cart::item.added.failed`             | `addItem`, `quickAdd`                | response or error, product id                                         |
| `cart::item.updated` / `cart::item.updated.failed`         | `updateItem`                         | response or error, item id                                            |
| `cart::item.deleted` / `cart::item.deleted.failed`         | `deleteItem`                         | response or error, item id                                            |
| `cart::image.deleted` / `cart::image.not.deleted`          | `deleteImage`                        | response or error, file id                                            |
| `cart::coupon.added` / `cart::coupon.addition.failed`      | `addCoupon`                          | response or error, cart id                                            |
| `cart::coupon.deleted` / `cart::coupon.deletion.failed`    | `deleteCoupon`                       | response or error, cart id                                            |
| `cart::details.fetched` / `cart::details.not.fetched`      | `details`                            | response or error                                                     |
| `cart::latest.fetched` / `cart::latest.failed`             | `latest`                             | response or error                                                     |
| `cart::offers.fetched` / `cart::offers.failed`             | `offers`                             | response or error                                                     |
| `cart::submitting`                                         | Before `submit` checks the cart      | none                                                                  |
| `cart::submitted` / `cart::submit.failed`                  | `submit`                             | response or error                                                     |
| `cart::quick-order.fetched`                                | `getQuickOrderSettings` worked       | response                                                              |
| `cart::quick-order.succeeded`                              | `createQuickOrder` worked            | response                                                              |
| `cart::quick-order.failed`                                 | Either quick-order call failed       | error                                                                 |
| `cart::price-quote.succeeded` / `cart::price-quote.failed` | `priceQuote`                         | response or error                                                     |
| `cart::success.reset`                                      | `reset`                              | none                                                                  |

Listen to `cart::updated` to keep a cart badge or summary in step. See [React to cart events](https://docs.salla.dev/twilight/react/recipes/react-to-cart-events).

## Gotchas [#gotchas]

* `updateItem` and `deleteItem` take the **cart item** id (`item.id` in the cart), not the product id.
* Calls to `updateItem` for the same item are sent one at a time, in order. Rapid quantity clicks do not overtake each other.
* `addItem` with `quantity` checks the option fields on the current product page first. If one is missing, the browser points at it and the add fails.
* When an add fails for a reason other than invalid data, the SDK resets the cart and tries once more.
* `details` and `offers` reject with a `CartNotCreated` error for a guest who has not added anything yet. Show an empty cart then.
* `submit` and a successful `priceQuote` leave the page: to checkout, to login, or back to the home page.

## See also [#see-also]

* [`cart` API module](https://docs.salla.dev/twilight/react/api/modules/cart)
* [Cart route](https://docs.salla.dev/twilight/react/routes/cart)
* [React to cart events](https://docs.salla.dev/twilight/react/recipes/react-to-cart-events)
* [Events](https://docs.salla.dev/twilight/react/sdk/events)
