# OWN eSIM — full agent ordering guide

> Keyless retail API. Prices match ownesim.com storefront. Orders: `order_type=api`, ids `own_order_api_agent_*`.
> Customer-facing product lines: **Basic** | **Premium** only. Never say eSIM Go, eSIM Tech, VRS, or “Basic ET” to customers.

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

## Product lines (customer)

| customer_line | What to say | Notes |
|---------------|-------------|-------|
| basic | Basic | May return several Basic options (different validity/price). Multi-country mix is Basic. |
| premium | Premium | Lifetime SIM, wallet refunds, top-up, destination swap, best network guarantee |

Internal `line` may be `basic`, `basic_et`, or `premium` for fulfillment — agents must present `customer_line` only.

## Perks

- **Basic:** best-value data; wallet refunds + top-up; long-validity options (~365 days); multi-country mix supported; some SKUs have no destination swap.
- **Premium:** lifetime eSIM on account; wallet refunds; top-up + destination swap; best network guarantee (all operators).

## Usage estimates

Video SD ≈ 500 MB/h (Netflix SD), Netflix HD ≈ 3 GB/h, social ≈ 100 MB/h, maps ≈ 5 MB/h. See `usage_estimate.summary` on each option.

## Conversation flow

1. `GET /destinations?q=Netherlands` (or ISO / mix)
2. `GET /options?countries=NL&days=30&data_mb=5120` → Basic + Premium options with `price_incl_vat`
3. `GET /perks` → Basic vs Premium
4. `POST /quote` `{ "option_id", "quantity" }` → `quote_id` (30 min)
5. Ask email; on agreement `POST /checkout` with `{ quote_id, email, confirm: true, expected_total_incl_vat_cents }`
6. Share **`checkout_url`** as one unbroken line — **keep the full `#fid…` fragment**. Truncating it opens Stripe with an error.
7. `GET /orders/status?order_id=&status_token=` until `ready`

### Netherlands example

```
GET https://ownesim.com/api/agent/options?countries=NL&days=30&data_mb=5120
→ quote → checkout with confirm:true → paste checkout_url verbatim
Customer lines: Basic | Premium only.
```

### NL + Sweden mix (cheapest)

```
GET https://ownesim.com/api/agent/options?countries=NL,SE&days=30&data_mb=5120
```
Pick the cheapest `customer_line=basic` option (or Premium if they want max network). Never invent a price.

## Coupons and VAT

- Default VAT: **NL 21%** when `customer_country` is omitted.
- EU destination: pass `customer_country` (ISO2) → that country's standard VAT rate.
- Outside EU: agent must ask the customer to confirm they live outside the EU, then re-quote with `confirm_outside_eu: true` for **0% VAT**. Never set this flag without an explicit yes.
- Coupons: optional `coupon_code` on `quote_order` / `quote_topup`. Percentage and fixed discounts only (applied excl-VAT before VAT). Free / 100% / wallet coupons are rejected — use the website checkout.
- Pass `channel: "whatsapp" | "mcp" | "rest"` on checkout so admin can see the medium.

## Stripe share rules

- Use `checkout_url` from the API response only (includes Stripe’s `#fid…` fragment).
- Paste as a single line; do not wrap, shorten, or strip characters after `#`.
- Truncating `#fid…` opens Stripe Checkout with an error.
- Session expires ~60 minutes; then re-quote + re-checkout.

## Safety

- Never create checkout without `confirm:true` and matching quoted total.
- Max 10 SIMs per order.
- Never invent ICCID / QR while status ≠ `ready`.
- Keep `status_token` private to the conversation.

## My eSIM (existing customers)

Auth: **email + ICCID** from the confirmation email (same rule as website login). Returns a signed `session_token` (2 hours). Tools accept `session_token` **or** `email` + `iccid`.

| Step | REST | MCP tool |
|------|------|----------|
| Verify | `POST /account/verify` | `verify_customer` |
| List SIMs | `GET /account/esims` | `list_esims` |
| Status / usage | `GET /account/esims/status?iccid=` | `get_esim_status` |
| Orders | `GET /account/orders` | `get_order_history` |
| Top-up quote | `POST /account/topup/quote` | `quote_topup` |
| Top-up pay | `POST /account/topup/checkout` | `create_topup_checkout` |
| Login email | `POST /account/login-link` | `send_login_link` |

### Auth rules

- Prompt: “Please share the email you ordered with and the ICCID (starts with 89…) from your confirmation email.”
- On `{ "error": "AUTH_REQUIRED", "ask_user_for": ["email","iccid"] }` → ask again. **Never guess.**
- Only return data for ICCIDs in the verified set.
- Failed verifications rate-limited (5 / 15 min per IP and email).
- `channel`: `whatsapp` | `mcp` | `rest` (default mcp over MCP, rest over REST). Stored in the session and stamped on top-up orders / emails.

### Top-up flow

1. `quote_topup` with owned `iccid` (+ optional `data_mb` / `days`)
2. Show total; on agreement `create_topup_checkout` with `confirm:true` and matching `expected_total_incl_vat_cents`
3. Share `checkout_url` as one unbroken line
4. Poll existing `get_order_status` until ready (top-up email sent by fulfillment)

### Login link

`send_login_link` only needs `email` (+ `channel`). Always returns a generic “if an account exists, a link was sent” message (no enumeration). Rate: 3 / hour / email.

Confirmation and login emails include a copy-paste **OWN eSIM login** credentials block (email + ICCID + Assistant URL) for WhatsApp / AI assistants.

## Partner API (different)

Authenticated B2B `/api/v1` (`bk_…` + IP whitelist) — not this retail flow.