Carts

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

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

POST/carts
GET/carts/{id}
GET/carts
DEL/carts/{id}

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.

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. 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 (60 by default) becomes abandoned, and Emailit emits cart.abandoned. Carts without a contact stay active.
Active again. Updating an abandoned cart makes it active and clears abandoned_at.
Converted. An order 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

idstring | numberRequired

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.

emailstring

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_idstring

The buyer’s contact (con_...). If no contact has this ID, Emailit looks the contact up by email.

anonymous_idstring

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.

currencystring

Three-letter ISO 4217 code. Defaults to the workspace currency in the commerce settings.

itemsobject[]

Up to 250 line items, in the same format as the items of Create or update an order. Items without a title, url or image_url take them from the catalog. line_items is also accepted.

totalnumber | string

Cart value. Defaults to the sum of the item totals.

checkout_urlstring

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.

statusstring

active (default) or converted. Send converted to close a cart yourself.

Returns

201 Created with the cart object when the cart is new, or 200 OK when an existing cart was updated. Returns 422 when a field is invalid.

POST/carts

Terminal

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 }
    ]
  }'

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"
}

JSON

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

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.

GET/carts/{id}

Path Parameters

idstringRequired

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

objectstring

Always cart.

idstring

Emailit cart ID (crt_...).

external_idstring

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_idstring | null

The contact the cart belongs to (con_...), or null while the buyer is unknown.

emailstring | null

The buyer’s email address.

statusstring

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.
converted: an order was placed for it, or you sent it with status set to converted.

currencystring | null

Three-letter ISO 4217 code of the amounts.

totalnumber

Cart value.

itemsobject[]

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_urlstring | null

Link that brings the buyer back to this cart.

sourcestring

api, or js for carts from the tracking script.

abandoned_atstring | null

When the cart was marked abandoned. Cleared when the cart is updated again.

converted_atstring | null

When the cart was converted.

converted_order_idstring | null

The order (ord_...) that converted the cart.

created_at, updated_atstring

When the cart was first stored and when it last changed, in ISO 8601 UTC.

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"
}

JSON

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

List carts

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

GET/carts

Query Parameters

pageinteger

Page number for pagination (minimum: 1, default: 1).

limitinteger

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

statusstring

Only carts with this status: active, abandoned or converted.

contact_idstring

Only carts of this contact (con_...).

matchstring

all (default) requires every filter. or matches any filter. See Filtering.

orderstring

Sort key for this list. See the sort keys below.

directionstring

asc or desc.

Filters and sort

List filters are one layer of key.condition=value query parameters. See Filtering for match, order, direction and the condition list per type.

Filter keys

Key	Type	Conditions	Notes
`external_id`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`email`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`status`	enum	exact, not_exact	Values: `active`, `abandoned`, `converted`
`total`	number	exact, not_exact, gt, gte, lt, lte, empty, not_empty
`currency`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`updated_at`	date	exact, before, after, empty, not_empty
`abandoned_at`	date	exact, before, after, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Sort keys

Pass order as one of these keys and direction as asc or desc: external_id, email, status, total, currency, updated_at, abandoned_at, created_at

Returns

A page of cart objects 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.

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
}

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.

DELETE/carts/{id}

Path Parameters

idstringRequired

The cart ID (crt_...) or the cart or checkout ID in your shop.

JSON

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

JSON

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