# Carts

> Shareable carts that close on WhatsApp

- Page: https://tbit.app/docs/api/carts
- Base URL: `https://rest-api.tbit.app/v1`
- Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable)

## Overview

Carts let a storefront visitor build a list of products and hand it off to a WhatsApp conversation with full context. A cart is a short-lived snapshot: it gets a 7-character code, is valid for 90 days, and is immutable: to change it, create a new one.

## How the Flow Works

1. A visitor on your storefront builds a list of products.
2. Your storefront creates a cart with POST /v1/carts and gets back a short code.
3. You send the visitor a link like https://<your-storefront>/c/<code> over WhatsApp.
4. When the conversation starts, your agent already has full context of what the visitor picked.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/v1/carts` | Create a shareable cart |
| `GET` | `/v1/carts/:code` | Resolve a cart by code |

## Create a Cart

Send 1-50 items, each referencing a product id with a qty between 1 and 99. The response is the cart's short code:

`POST /v1/carts`

```bash
curl -X POST "https://rest-api.tbit.app/v1/carts" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "prod_id_1",
        "qty": 2
      },
      {
        "id": "prod_id_2",
        "qty": 1
      }
    ]
  }'
```

Response:

```json
{
  "data": {
    "code": "K3F9X2A"
  }
}
```

## Get a Cart

Resolve a code back into its items, each one a full product object plus qty. Carts are tenant-isolated: a key only resolves carts created for its own agent: anything else returns 404:

`GET /v1/carts/K3F9X2A`

```bash
curl "https://rest-api.tbit.app/v1/carts/K3F9X2A" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Response:

```json
{
  "data": {
    "code": "K3F9X2A",
    "created_at": "2024-09-01T12:00:00Z",
    "items": [
      {
        "_id": "prod_id_1",
        "kind": "product",
        "title": "Kit fiesta dinosaurios",
        "currency": "COP",
        "base_price": 95000,
        "qty": 2
      },
      {
        "_id": "prod_id_2",
        "kind": "product",
        "title": "Piñata dinosaurio",
        "currency": "COP",
        "base_price": 45000,
        "qty": 1
      }
    ]
  }
}
```

## Notes

- Codes are 7 characters long.
- Carts are valid for 90 days.
- Carts are immutable: create a new one to change the items.
- Carts from other agents (or unknown codes) return 404.