# Carts API

> Send your buyers’ carts so Emailit can detect abandoned carts.

Base URL: `https://api.emailit.com/v2`. Authenticate with `Authorization: Bearer <API key>`.

## Create or update a cart — POST /carts

> Send the buyer's current cart from your shop. Idle carts of known contacts become abandoned and emit cart.abandoned. Alpha: open to the Emailit team only.

# Create or update a cart

Send the buyer's current cart whenever it changes. The cart is keyed by its `id` in your shop: send the same `id` again and the stored cart is updated. Each call replaces the cart's `items` and `total`. The email, contact, currency and checkout URL are kept when you leave them out. Requires an API key with the `full` or `events` scope. With an `events` key, the response holds only `object`, `id` and `external_id`.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

The [tracking script](/docs/commerce/connect-your-shop/#the-tracking-script) can send carts from the browser instead.

A new cart, or a change to a cart's items, total, status or contact, emits [`cart.updated`](/docs/webhooks/events/cart/updated/). Sending the same cart again emits nothing.

How a cart moves between statuses:

- **Abandoned.** A cart that belongs to a contact, has at least one item and isn't updated for the `cart_abandon_minutes` of the [commerce settings](/docs/api-reference/commerce/get-settings/) (60 by default) becomes `abandoned`, and Emailit emits [`cart.abandoned`](/docs/webhooks/events/cart/abandoned/). Carts without a contact stay `active`.
- **Active again.** Updating an abandoned cart makes it `active` and clears `abandoned_at`.
- **Converted.** An [order](/docs/api-reference/orders/create/) with the same `cart_id` converts the cart. A new order from the same contact also converts that contact's carts that were last updated before the order. A converted cart stays converted when you update it.

`POST /carts`

## Request Body

- `id` (string | number, required): The cart or checkout ID in your shop, up to 255 characters. Stored as `external_id`. Send the same value as `cart_id` on the order. You can also send it as `external_id` or `cart_id`.

- `email` (string): The buyer's email address. Links the cart to the contact with this address. Carts never create contacts: a cart without a matching contact can't become abandoned. `customer.email` is also accepted.

- `contact_id` (string): The buyer's contact (`con_...`). If no contact has this ID, Emailit looks the contact up by `email`.

- `anonymous_id` (string): The visitor ID of the tracking script, up to 255 characters. When that visitor later identifies, carts with this ID and no contact are linked to the contact.

- `currency` (string): Three-letter ISO 4217 code. Defaults to the workspace currency in the [commerce settings](/docs/api-reference/commerce/get-settings/).

- `items` (object[]): Up to 250 line items, in the same format as the `items` of [Create or update an order](/docs/api-reference/orders/create/). Items without a `title`, `url` or `image_url` take them from the [catalog](/docs/api-reference/products/create/). `line_items` is also accepted.

- `total` (number | string): Cart value. Defaults to the sum of the item totals.

- `checkout_url` (string): An `http` or `https` link that brings the buyer back to this cart, up to 2,048 characters. Emails can link to it with the [cart block](/docs/campaigns/products-and-coupons/#the-cart).

- `status` (string): `active` (default) or `converted`. Send `converted` to close a cart yourself.

## Returns

`201 Created` with the [cart object](/docs/api-reference/carts/get/) when the cart is new, or `200 OK` when an existing cart was updated. Returns `422` when a field is invalid.
**Request** `POST /carts`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/carts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "c-58f1a2",
    "email": "ada@example.com",
    "currency": "USD",
    "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "quantity": 1, "price": 89 }
    ]
  }'
```

**201**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "active",
  "currency": "USD",
  "total": 89,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": null,
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:12:47.630Z"
}
```

**422**

```json
{
  "message": "Validation failed. checkout_url: must be an http(s) URL",
  "errors": {
    "checkout_url": [
      "must be an http(s) URL"
    ]
  }
}
```

---
Source: https://emailit.com/docs/api-reference/carts/upsert/

## Retrieve a cart — GET /carts/{id}

> Retrieve a cart by its Emailit ID or by the cart or checkout ID in your shop. Alpha: open to the Emailit team only.

# Retrieve a cart

Retrieve a cart by its Emailit ID or by the cart or checkout ID in your shop. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`GET /carts/{id}`

## Path Parameters

- `id` (string, required): The cart ID (`crt_...`) or the cart or checkout ID in your shop (`external_id`). URL-encode shop IDs that contain special characters.

## The cart object

- `object` (string): Always `cart`.

- `id` (string): Emailit cart ID (`crt_...`).

- `external_id` (string): The cart or checkout ID in your shop: the `id` you sent. Carts from the tracking script without their own ID use `web:` plus the visitor's anonymous ID.

- `contact_id` (string | null): The contact the cart belongs to (`con_...`), or `null` while the buyer is unknown.

- `email` (string | null): The buyer's email address.

- `status` (string): - `active`: the buyer is still shopping. - `abandoned`: the cart belongs to a contact, has items and hasn't changed for the `cart_abandon_minutes` of the [commerce settings](/docs/api-reference/commerce/get-settings/). - `converted`: an order was placed for it, or you sent it with `status` set to `converted`.

- `currency` (string | null): Three-letter ISO 4217 code of the amounts.

- `total` (number): Cart value.

- `items` (object[]): Line items. Each has `product_id` (the product ID in your shop), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `url` and `image_url`.

- `checkout_url` (string | null): Link that brings the buyer back to this cart.

- `source` (string): `api`, or `js` for carts from the tracking script.

- `abandoned_at` (string | null): When the cart was marked abandoned. Cleared when the cart is updated again.

- `converted_at` (string | null): When the cart was converted.

- `converted_order_id` (string | null): The order (`ord_...`) that converted the cart.

- `created_at, updated_at` (string): When the cart was first stored and when it last changed, in ISO 8601 UTC.

**Request** `GET /carts/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "abandoned",
  "currency": "USD",
  "total": 107,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": "2026-10-08T13:31:04.118Z",
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:28:51.902Z"
}
```

**404**

```json
{
  "error": "Cart not found",
  "message": "Cart not found."
}
```

---
Source: https://emailit.com/docs/api-reference/carts/get/

## List carts — GET /carts

> List carts, most recently updated first, filtered by status or contact. Alpha: open to the Emailit team only.

# List carts

List carts, most recently updated first. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`GET /carts`

## Query Parameters

- `page` (integer): Page number for pagination (minimum: 1, default: 1).

- `limit` (integer): Number of carts to return (minimum: 1, maximum: 100, default: 25).

- `status` (string): Only carts with this status: `active`, `abandoned` or `converted`.

- `contact_id` (string): Only carts of this contact (`con_...`).

- `match`, `order`, `direction`: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## Filters and sort

Filter and sort keys: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## Returns

A page of [cart objects](/docs/api-reference/carts/get/) in `data`, with `total_records`, `next_page_url` and `previous_page_url`. The page URLs carry only `page` and `limit`, so add your filters again when you follow them.
**Request** `GET /carts`

**cURL**

```bash
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "cart",
      "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
      "external_id": "c-58f1a2",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "abandoned",
      "currency": "USD",
      "total": 89,
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": "42-blue",
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
      "source": "api",
      "abandoned_at": "2026-10-08T13:31:04.118Z",
      "converted_at": null,
      "converted_order_id": null,
      "created_at": "2026-10-08T12:12:47.630Z",
      "updated_at": "2026-10-08T12:28:51.902Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Source: https://emailit.com/docs/api-reference/carts/list/

## Delete a cart — DELETE /carts/{id}

> Delete a cart. Alpha: open to the Emailit team only.

# Delete a cart

Delete a cart. Orders that converted it aren't affected. If you send a cart with the same `id` again, it's stored as a new cart. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`DELETE /carts/{id}`

## Path Parameters

- `id` (string, required): The cart ID (`crt_...`) or the cart or checkout ID in your shop.

**Request** `DELETE /carts/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "deleted": true
}
```

**404**

```json
{
  "error": "Cart not found",
  "message": "Cart not found."
}
```

---
Source: https://emailit.com/docs/api-reference/carts/delete/