# OWN eSIM — full agent ordering guide

> Keyless retail API for AI agents. Prices match the ownesim.com storefront (label ceiling margin + VAT). Orders are tagged `order_type=api` (`own_order_api_agent_*`).

Base: https://ownesim.com/api/agent
MCP: https://ownesim.com/mcp
OpenAPI: https://ownesim.com/api/agent/openapi.json

## Product lines

| Line | Provider | Notes |
|------|----------|-------|
| basic | eSIM Go | Fixed country / regional bundles (e.g. Europe Lite / Europe+). No destination swap. |
| basic_et | eSIM Tech | Custom data MB; multi-country mix when 2+ ISO codes. Top-up + destination swap. Long validity (~365 days). |
| premium | VRS / IoT Connect | Lifetime eSIM on account, wallet refunds, top-up, destination swap, best network guarantee. |

## Perks (compare_lines)

- Premium: lifetime SIM (stays on account), wallet refunds, top-up, destination swap, best network guarantee (all operators).
- Basic ET: refund, wallet, top-up, destination swap; mix zones.
- Basic: refund, wallet, top-up — no destination swap.

## Usage estimates

Data usage guidance uses storefront rates: video SD ≈ 500 MB/h (Netflix SD), Netflix HD ≈ 3 GB/h, social ≈ 100 MB/h, maps ≈ 5 MB/h. Example: 5GB / 7 days ≈ 0.7 GB/day ≈ ~1.4h Netflix SD/day or ~15m HD/day.

## Conversation flow

1. `GET /destinations?q=Europe` or MCP `search_destinations`
2. `GET /options?countries=NL,DE&days=7&data_mb=1024` → Basic + Basic ET + Premium options with `price_incl_vat` and `usage_estimate`
3. `GET /perks` → basic vs premium comparison
4. `POST /quote` `{ "option_id", "quantity" }` → `quote_id` (30 min)
5. Ask user for email; on agreement `POST /checkout` with `{ quote_id, email, confirm: true, expected_total_incl_vat_cents }` → `checkout_url`, `order_id`, `status_token`
6. Customer pays via Stripe Checkout Session (one-time, expires ~60 min)
7. `GET /orders/status?order_id=&status_token=` until `status=ready` → ICCID, LPA, QR, iPhone/Android 1-tap links
8. Email is also sent by the normal success / transactional flow after payment webhook

## Safety rules for agents

- Never create checkout without `confirm:true` and an agreed total matching the quote.
- Max 10 SIMs per order.
- Never invent ICCID / QR while status is not `ready`.
- Reuse the same `order_id` / `status_token` when polling.
- Do not expose `status_token` in public crawls or logs shared with third parties.

## Partner API (authenticated, separate)

B2B Partner API at `/api/v1` requires `bk_…` keys + IP whitelist and returns acquisition prices — not this retail agent API.