Carts - Salesive Docs

What an app can read

The carts API is a read-only view of a store’s customer carts. Use it to recover an abandoned cart, show a merchant what a shopper left behind, or re-fetch the cart a cart webhook pointed at. It is not the shopper-facing /cart endpoint. That one belongs to the storefront and acts on the signed-in shopper’s own cart. This mount is for an installed app or a staff member and covers every customer cart in the store. Cart writes are shopper actions on the storefront, so there are no create, update or delete routes here. An app reads a cart; it never edits one.

Authentication and scope

Authorization: Bearer app_<your-app-access-token>

The store comes from the installation bound to your token, never from a header or query parameter. Both routes require the READ_CART_CONTENTS scope. A call without it is refused with 403 naming the missing scope.

READ_CART_CONTENTS unlocks the fetch API on its own. READ_CARTS is the separate scope that makes the storefront send cart webhooks. An app can hold either without the other: with only READ_CART_CONTENTS it can fetch carts but receives no cart events; with only READ_CARTS it receives notify-only events and cannot fetch the cart.

Cart reads expose cart contents only. The shopper is identified by id, never by name, email or phone. Pair with READ_CUSTOMERS if you need the customer’s profile.

Endpoints

All paths are under https://api.salesive.com/api/v1.

Method	Path	What it does
`GET`	`/carts`	List the store’s customer carts, most recently updated first
`GET`	`/carts/:customerId`	Read one customer’s cart

List carts

curl "https://api.salesive.com/api/v1/carts?status=abandoned&limit=20" \
  -H "Authorization: Bearer app_<your-app-access-token>"

Query	Default	Notes
`page`	`1`	Whole number, 1 or more.
`limit`	`20`	Whole number from 1 to 100. Values outside the range are clamped.
`status`	`active`	`active` returns carts that still hold items, `abandoned` returns active carts idle past the abandonment window, `all` returns every cart including empty ones.

{
  "status": 200,
  "success": true,
  "message": "Carts retrieved successfully",
  "data": {
    "carts": [
      {
        "_id": "66c2a1b3c4d5e6f7a8b9c0d1",
        "customerId": "66b1f0a3c2d4e5f6a7b8c9d0",
        "itemCount": 2,
        "totalPrice": 7000,
        "items": [
          {
            "_id": "66c2a1b3c4d5e6f7a8b9c0e1",
            "itemType": "product",
            "product": {
              "_id": "66d3b2c4d5e6f7a8b9c0d1e2",
              "name": "Jollof rice",
              "price": 3500,
              "images": ["https://cdn.salesive.com/products/jollof.png"],
              "image": "https://cdn.salesive.com/products/jollof.png"
            },
            "name": "Jollof rice",
            "image": "https://cdn.salesive.com/products/jollof.png",
            "price": 3500,
            "quantity": 2,
            "selectedAddons": []
          }
        ],
        "abandoned": false,
        "lastActivityAt": "2026-11-08T12:25:00.000Z",
        "lastAbandonmentAt": null,
        "updatedAt": "2026-11-08T12:25:00.000Z",
        "createdAt": "2026-11-07T18:10:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

Cart fields

Field	Type	Description
`_id`	string	The cart id.
`customerId`	string	The shopper’s user id. This is the `resourceId` and `customerId` a cart webhook carries.
`itemCount`	number	Sum of every line’s `quantity`.
`totalPrice`	number	Cart value in the store currency, in major units. See Money and units.
`items`	array	The cart’s line items.
`abandoned`	boolean	`true` when the cart holds at least one item and has been idle past the abandonment window.
`lastActivityAt`	string or `null`	When the cart’s contents last changed. `null` on carts written before this field existed.
`lastAbandonmentAt`	string or `null`	The `lastActivityAt` value at which the abandonment job last flagged this cart.
`updatedAt`	string	Last write to the cart document. The storefront also bumps this on reads, so use `lastActivityAt` to judge shopper activity.
`createdAt`	string	When the cart was created.

Item fields

Field	Type	Description
`_id`	string	The line id.
`itemType`	string	`product`, `food` or `service`.
`product`	object	Present on product lines: the populated product as `{ _id, name, price, images, image }`.
`food`	object	Present on food lines: the populated food as `{ _id, name, price, images }`.
`service`	object	Present on service lines: the populated service as `{ _id, name, price, images }`.
`variant`	string	The selected variant id, when the line is for a specific variant.
`sku`	string	The variant SKU, when recorded.
`variantAttributes`	object	The selected variant attributes as a string map, when recorded.
`selectedAddons`	array	Add-ons chosen for the line, each `{ addonId, name, description, image, price, quantity }`.
`name`	string	The line name recorded by the storefront.
`image`	string	The line image recorded by the storefront.
`price`	number	The unit price on the line, in major units.
`quantity`	number	How many of the line the shopper added.

name, image and price are the values recorded on the line itself. The populated product, food or service object carries the current catalog values, so a later price change shows up there while the line keeps the values the storefront recorded. A populated catalog object is null if that record has since been deleted.

Get one customer’s cart

curl "https://api.salesive.com/api/v1/carts/66b1f0a3c2d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer app_<your-app-access-token>"

data is the same cart object shown above, not a list:

{
  "status": 200,
  "success": true,
  "message": "Cart retrieved successfully",
  "data": {
    "_id": "66c2a1b3c4d5e6f7a8b9c0d1",
    "customerId": "66b1f0a3c2d4e5f6a7b8c9d0",
    "itemCount": 2,
    "totalPrice": 7000,
    "items": [
      {
        "_id": "66c2a1b3c4d5e6f7a8b9c0e1",
        "itemType": "product",
        "product": {
          "_id": "66d3b2c4d5e6f7a8b9c0d1e2",
          "name": "Jollof rice",
          "price": 3500,
          "images": ["https://cdn.salesive.com/products/jollof.png"],
          "image": "https://cdn.salesive.com/products/jollof.png"
        },
        "name": "Jollof rice",
        "image": "https://cdn.salesive.com/products/jollof.png",
        "price": 3500,
        "quantity": 2,
        "selectedAddons": []
      }
    ],
    "abandoned": false,
    "lastActivityAt": "2026-11-08T12:25:00.000Z",
    "lastAbandonmentAt": null,
    "updatedAt": "2026-11-08T12:25:00.000Z",
    "createdAt": "2026-11-07T18:10:00.000Z"
  }
}

The path segment is the shopper’s user id, which is what a cart webhook delivers as resourceId. A Customer _id is also accepted and is resolved to that customer’s user. The lookup is scoped to your store, so an id from another store returns 404. A customer with no cart returns 404 Cart not found.

When to call it

After a cart webhook. carts/item_added, carts/updated, carts/item_removed, carts/cleared and carts/abandoned carry the shopper’s user id as resourceId (and again as customerId). Call GET /carts/:customerId to read the current line items and value. The event itself is notify-only: it may carry a small cart aggregate (itemCount and totalPrice) when your install holds READ_CART_CONTENTS, but never the line items.
To find carts to recover. List with status=abandoned and work through the carts the abandonment job has flagged.
To show a merchant a shopper’s cart. Read one cart by customer id.

Abandonment

A cart is abandoned when both are true:

it holds at least one item, and
its last content change is at least CART_ABANDON_IDLE_MINUTES old (30 minutes by default).

The idle clock runs from lastActivityAt, falling back to updatedAt for carts written before that field existed. It deliberately does not use updatedAt alone, because the storefront bumps updatedAt when it reads a cart. status=abandoned applies the same rule, so the list and the carts/abandoned webhook agree.

Errors

Status	Meaning
`401`	The token is missing, expired or revoked, or the app is no longer installed on the store.
`403`	The app does not hold `READ_CART_CONTENTS`. The message names the missing scope.
`404`	No cart exists for that customer in this store.

Next steps

Webhooks

The cart topics and the per-topic payload additions.

Wishlists

Read the products a customer saved for later.

Customers

Resolve a customerId to a customer profile with READ_CUSTOMERS.

Money and units

How totalPrice and every other amount is expressed.

​What an app can read

​Authentication and scope

​Endpoints

​List carts

​Cart fields

​Item fields

​Get one customer’s cart

​When to call it

​Abandonment

​Errors

​Next steps

Webhooks

Wishlists

Customers

Money and units

What an app can read

Authentication and scope

Endpoints

List carts

Cart fields

Item fields

Get one customer’s cart

When to call it

Abandonment

Errors

Next steps