> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesive.com/llms.txt > Use this file to discover all available pages before exploring further. # Carts > Read a store's customer carts from an installed app: list carts, re-fetch the cart a cart webhook pointed at, and read the item count, value and line items. Requires READ_CART_CONTENTS. ## 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 ```http theme={null} Authorization: Bearer app_ ``` 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. > [!NOTE] > > `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 ```bash theme={null} curl "https://api.salesive.com/api/v1/carts?status=abandoned&limit=20" \ -H "Authorization: Bearer app_" ``` | 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. | ```json theme={null} { "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](https://docs.salesive.com/apps-api/introduction.md#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 ```bash theme={null} curl "https://api.salesive.com/api/v1/carts/66b1f0a3c2d4e5f6a7b8c9d0" \ -H "Authorization: Bearer app_" ``` `data` is the same cart object shown above, not a list: ```json theme={null} { "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 > [card] [Webhooks](https://docs.salesive.com/apps-api/webhooks.md) > > The cart topics and the per-topic payload additions. > [card] [Wishlists](https://docs.salesive.com/apps-api/wishlist.md) > > Read the products a customer saved for later. > [card] [Customers](https://docs.salesive.com/apps-api/endpoint/customers/list-customers.md) > > Resolve a `customerId` to a customer profile with `READ_CUSTOMERS`. > [card] [Money and units](https://docs.salesive.com/apps-api/introduction.md#money-and-units) > > How `totalPrice` and every other amount is expressed. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.