# Buying a SimPig eSIM for someone, as an assistant

You can do the whole thing without a login, and you never need the person's SimPig password: there is no
account step in buying. The person only has to pay. If a web page sends you to a sign-in screen, you have taken
the human route by mistake; use the calls below instead (or, on simpig.com/checkout/{productId}, open "Are you an
assistant buying for someone else?").

## 1. Find a plan

```
GET https://simpig.com/api/v1/catalog/destinations
GET https://simpig.com/api/v1/catalog/plans/JP          (code or slug; regional plans that cover JP are included, isRegional: true)
GET https://simpig.com/api/v1/catalog/trip?to=JP,KR,TH  (several countries: `covering` = one plan for the whole trip, `singles` = per country)
```

For a trip through several countries prefer a `covering` plan (one eSIM, one install); when `covering` is empty,
pick one plan per country from `singles`. The shop lists nothing under 1 GB.

Each plan has `productId`, `volumeBytes`, `durationDays`, `priceMinor` and `currency` (AUD cents: 1999 = A$19.99),
`supportsTopup`, `operators`. Only fixed-data plans are sold; the clock starts when the eSIM first connects abroad.

## 2. Start the order

```
POST https://simpig.com/api/v1/agent/orders
{ "email": "traveller@example.com", "productId": "…", "qty": 1,
  "idempotencyKey": "your-unique-key", "callbackUrl": "https://your.app/hook" }
```

Answer: `order` (with `ref`, `status: pending_payment`, `payUrl`), `statusUrl`, `orderToken`, `next`.

- `payUrl` is Stripe's hosted page (card, Apple Pay, Google Pay). Give it to the person. It expires in 30 minutes.
- `orderToken` is returned **only here**. Keep it; it is the only way to read the order without signing in.
- `idempotencyKey`: the same key returns the same order (`existing: true`) and no new token.
- Nothing is charged until the person pays. Limits: 5 eSIMs per order, 10 orders per email per hour.

## 3. Wait for payment and provisioning

```
GET https://simpig.com/api/v1/agent/orders/{ref}
Authorization: Bearer <orderToken>
```

`status` moves `pending_payment → paid → provisioning → fulfilled` (usually within a minute of payment). Poll every
5–10 seconds, or give a `callbackUrl` and we POST `{ ref, status, statusUrl, fulfilledAt }` when it is fulfilled.
`expired` means the pay link lapsed unpaid; start again. `failed` means our supplier could not provision; the person
is emailed and refunded.

## 4. Hand over the eSIM

Once `fulfilled`, each `esims[]` entry carries `install`:

- `iosInstallUrl` (iPhone one tap) and `androidInstallUrl` when available,
- `ac`, the LPA activation string, to render as a QR code for another device,
- `smdpAddress`, `matchingId`, `confirmationCode` for manual entry (Settings → Mobile Service → Add eSIM → enter details).

The same details are emailed to the person, and appear at https://me.simpig.com once they sign in with that email (an account is made for it; "Forgot it?" on the
sign-in page sets the first password). Treat `ac` as a secret: anyone holding it can install the profile.

## MCP

The same flow as tools: add `https://simpig.com/api/mcp` as a Streamable HTTP MCP server (no auth).
`search_destinations`, `list_plans`, `plans_covering`, `get_plan`, `start_order`, `order_status`.

## Rules

Refund in full while the eSIM is uninstalled (ask hello@simpig.com with the order ref); none once installed.
Prices include everything. Rate limits apply per IP and per email; use `idempotencyKey` on retries.