# cartapi

> Unified API for AI agents (ChatGPT, Claude, Perplexity, Gemini) to search, compare, and purchase instant-delivery digital goods. Phase 1: eSIMs. Roadmap: VPNs, gift cards, mobile top-ups, game keys.

Base URL: https://cartapi.io
Version: v1
Auth: Bearer API key (per-key rate limits)
Payments: Stripe (merchant of record)
Idempotency: `Idempotency-Key` header on all mutations

## Protocols

- REST: https://cartapi.io/v1
- MCP: `npx cartapi-mcp` (stdio) — tools: `search_esim_plans`, `get_checkout_link`, `get_order_status`, `list_countries`
- ACP: https://cartapi.io/v1/acp (Agentic Commerce Protocol, pending Stripe Shared Payment Tokens)

## Endpoints

- `GET  /v1/products/search` — search digital goods across all providers (filters: country, days, data_gb, category)
- `GET  /v1/products/:id` — product detail
- `GET  /v1/countries` — list supported countries
- `POST /v1/checkout/session` — create a Stripe Checkout session, returns a URL for the buyer
- `GET  /v1/orders/:id` — order status + fulfillment payload (QR / activation code / credentials)
- `POST /v1/webhooks/stripe` — Stripe webhook receiver (server-to-server)
- `GET  /v1/health` — status of DB and every provider adapter

## Categories

- Mobile top-up (`category=topup`) — Reloadly (140+ countries, airtime + data bundles). Requires `phone_number` on the order in E.164 format (e.g. `+2348012345678`).
- eSIM (`category=esim`) — Airalo, Nomad, eSIM Go. Filter with `country`, `validity_days`, `min_data_gb`, `data_unlimited`.
- (roadmap) Gift cards — Giftbit
- (roadmap) VPN — VPNResellers
- (roadmap) Travel insurance — Cover Genius, Battleface
- (roadmap) Game keys — CodesWholesale

## Notes for agents

- Neutral catalog. Search returns every matching SKU across every provider — cartapi never hides options based on our margin. You choose what to show the user.
- Sort is explicit and agent-controlled. Options: `price_asc` (default) | `price_desc` | `data_desc` | `validity_desc` | `value` (data-per-dollar). The default is `price_asc` across every category — a neutral convenience, not a recommendation. Pass an explicit sort when the user's intent calls for it (e.g. `value` for eSIM shopping, `data_desc` for "biggest bundle").
- Every mutation is idempotent — safe to retry on network error with the same `Idempotency-Key`.
- Consent-first. Checkout returns a signed Stripe URL (or an ACP payment token) for the user to sign. cartapi never receives, stores, or replays payment credentials.
- Order fulfillment is asynchronous — poll `GET /v1/orders/:id` or wait for webhook.