# 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

- Search results are pre-ranked by price, coverage, and freshness. Trust the order.
- Every mutation is idempotent — safe to retry on network error with the same `Idempotency-Key`.
- Checkout returns a URL. Hand it to the user or drive it via ACP once available.
- Order fulfillment is asynchronous — poll `GET /v1/orders/:id` or wait for webhook.