> ## Documentation Index > Fetch the complete documentation index at: https://docs.keebai.com/llms.txt > Use this file to discover all available pages before exploring further. # GET /v1/ecommerce/carts > List carts, including abandoned ones, filtered by origin and recovery status. Returns a paginated list of carts. This is where abandoned-cart recovery starts: filter by `recovery_status=pending` to find the ones nobody has followed up on yet. Results cover the whole **company**, not just the project your token belongs to. ## Endpoint ``` GET https://api.keebai.com/v1/ecommerce/carts ``` ## Required scope `ecommerce:carts:read` ## Headers | Header | Required | Value | | --------------- | -------- | ------------------------ | | `Authorization` | Yes | `Bearer kbai_pk_` | ## Query parameters | Field | Type | Required | Description | | ----------------- | --------- | -------- | ---------------------------------------------------- | | `source` | `string` | No | Origin of the cart. | | `integration_id` | `string` | No | `ObjectId` of the source integration. | | `recovery_status` | `string` | No | `pending`, `contacted`, `recovered`, or `discarded`. | | `limit` | `integer` | No | Page size, `1`–`200`. Defaults to 50. | | `offset` | `integer` | No | Records to skip. Defaults to 0. | ## Example request ```bash curl theme={null} curl -G https://api.keebai.com/v1/ecommerce/carts \ -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --data-urlencode "recovery_status=pending" \ --data-urlencode "limit=50" ``` ```js JavaScript theme={null} const params = new URLSearchParams({ recovery_status: "pending", limit: "50", }); const response = await fetch( `https://api.keebai.com/v1/ecommerce/carts?${params}`, { headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` } }, ); const { data, total } = await response.json(); ``` ```python Python theme={null} import os, requests resp = requests.get( "https://api.keebai.com/v1/ecommerce/carts", headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"}, params={"recovery_status": "pending", "limit": 50}, timeout=10, ) resp.raise_for_status() carts = resp.json()["data"] ``` ## Response ### 200 OK ```json theme={null} { "data": [ { "_id": "65c2d3e4f5a6b7c8d9e0f1a2", "source": "shopify", "integration_id": "65b1c2d3e4f5a6b7c8d9e0f1", "external_id": "gid://shopify/Cart/abc123", "customer_id": "65a1f2b3c4d5e6f7a8b9c0d1", "customer_name": "Juan Pérez", "customer_email": "juan@example.com", "customer_phone": "+56912345678", "items": [ { "product_id": "65d3e4f5a6b7c8d9e0f1a2b3", "product_name": "Zapatilla Runner Pro", "sku": "SKU-1234", "quantity": 1, "unit_price": 5990000, "subtotal": 5990000 } ], "total": 5990000, "currency": "CLP", "recovery_status": "pending", "recovery_url": "https://tienda.example.com/cart/recover/abc123", "abandoned_at": "2026-05-02T14:31:07.221Z", "created_at": "2026-05-02T13:58:02.100Z", "updated_at": "2026-05-02T14:31:07.221Z" } ], "total": 1, "limit": 50, "offset": 0 } ``` ### 400 Bad Request `limit` above 200, negative `offset`, or an unknown query parameter. ### 401 Unauthorized Missing, invalid, revoked, or expired token. ### 403 Forbidden The token does not have the `ecommerce:carts:read` scope. ### 502 Bad Gateway The ecommerce service could not answer. ## Operational notes * **An abandoned cart has `abandoned_at` set and `completed_at` absent.** A cart that was completed keeps `completed_at` and is no longer worth recovering, whatever its `recovery_status` says. * **`recovery_url` is the whole point.** It drops the customer back into checkout with the cart intact. Pairing it with [a `cta_url` message](/dev/endpoints/messages-send) is the intended recovery flow. * **`customer_id` is the contact id**, the same one [`GET /v1/contacts`](/dev/endpoints/contacts-list) returns — but only when Keebai could match the shopper to a known contact. On anonymous carts it is absent and you only have the email or phone the customer typed. * **Marking a cart as contacted is not exposed here.** This surface is read-only; the status changes from the portal or from the recovery automation. ## OpenAPI ````yaml GET /v1/ecommerce/carts openapi: 3.0.0 info: title: Keebai Public API description: Superficie pública REST autenticada con Personal Access Tokens (PAT). version: 1.0.0 contact: {} servers: - url: https://api.keebai.com description: Production security: [] tags: [] paths: /v1/ecommerce/carts: get: tags: - ecommerce summary: Listar carritos description: >- Devuelve los carritos de la company, incluidos los abandonados. Filtrable por origen, integración y estado de recuperación. operationId: PublicEcommerceController_listCarts parameters: - name: limit required: false in: query schema: minimum: 1 maximum: 200 default: 50 type: number - name: offset required: false in: query schema: minimum: 0 default: 0 type: number - name: source required: false in: query description: Origen del carrito schema: type: string - name: integration_id required: false in: query description: ObjectId de la integración de origen schema: type: string - name: recovery_status required: false in: query description: Estado de recuperación del carrito abandonado schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicCartListResponseDto' security: - PAT: [] components: schemas: PublicCartListResponseDto: type: object properties: total: type: number limit: type: number offset: type: number data: type: array items: $ref: '#/components/schemas/PublicCartResponseDto' required: - total - limit - offset - data PublicCartResponseDto: type: object properties: _id: type: string description: ObjectId del carrito source: type: string description: Origen del carrito integration_id: type: string description: ObjectId de la integración de origen external_id: type: string description: Identificador en el sistema externo customer_id: type: string description: ObjectId del contacto customer_name: type: string customer_email: type: string customer_phone: type: string items: type: array items: $ref: '#/components/schemas/PublicCartItemDto' total: type: number currency: type: string recovery_status: type: string description: pending | contacted | recovered | discarded recovery_url: type: string description: URL para que el cliente retome el carrito abandoned_at: type: string format: date-time completed_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - _id - source - items - total - currency - recovery_status - created_at - updated_at PublicCartItemDto: type: object properties: product_id: type: string description: ObjectId del producto en Keebai product_name: type: string sku: type: string quantity: type: number unit_price: type: number subtotal: type: number modifiers_summary: type: string comment: type: string required: - product_name - quantity - unit_price - subtotal securitySchemes: PAT: scheme: bearer bearerFormat: kbai_pk_ type: http description: >- Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal con permiso `developer.manage_tokens`. ````