eSIMian — purchasing instructions for AI agents

Quick start

1. Identify destination countries, trip duration and required data. Ask only for missing information that could change the recommendation.
2. Fetch the filtered catalog: https://esimian.com/agent-catalog/checkout-v2.json?country=JP&min_days=7.
3. Keep only plans that cover every destination, last for the full trip, satisfy the requested data and have enable_checkout: true.
4. Choose the lowest-priced eligible plan. On a tie, prefer the simpler geographic scope. Never invent claims about carrier speed or quality.
5. Summarize coverage, validity, data, operator, price and any exceptional activation or fair-use rule. Ask for confirmation only when purchasing authority is not already explicit.
6. Follow Checkout decision, then report the delivery outcome honestly.

DEFAULT RULE → lowest-priced plan satisfying every stated coverage, duration and data constraint.

Resource map

• https://esimian.com/acp/destinations.jsonSupported destinations and normalized country codes. Use it to validate a supplied place; if none was supplied, ask the human.
• https://esimian.com/agent-catalog/checkout-v2.json?country=XX&min_days=NCurrent filterable catalog. Read product ids, prices, attributes and checkout URLs here.
• product.linkProduct information only. Never present it as payment or checkout.
• product.checkout_linkMachine GET endpoint. Read its JSON; never give this URL to the human.
• product.human_checkout_urlStable human payment handoff. Copy it exactly when machine execution is blocked.
• poll_urlFresh session status and delivery. Always use the newest URL returned by the server.

Never guess a product id. If a filter returns no products, relax optional filters or ask the human for the missing constraint.

Selection algorithm

1. Coverage must include every stated destination.
2. validity_days must cover the full trip.
3. data_allowance must meet the requested usage.
4. availability must be in_stock and enable_checkout must be true.
5. Sort remaining plans by price ascending. On a tie, prefer the narrower geographic scope.

Fields that change what you tell the human

• validity_starts absent means validity starts on first network connection. If it says installation, warn the human not to install too early.
• unlimited_fair_usage_policy: true means “Unlimited” is throttled after a fair-use threshold. Disclose it.
• Voice and SMS are absent unless voice_minutes or text_messages explicitly say otherwise.
• operator identifies the carrier. Do not infer speed or reliability from it.

Checkout decision

NEVER substitute link, /plans/… or checkout_link for human_checkout_url.

Machine-readable GET path

# Read the exact URL supplied in the selected feed product.
GET product.checkout_link

→ requires_escalation + continue_url + poll_url + session id

# Send only continue_url to the human. Keep poll_url private for delivery.

Advanced clients: the full ACP POST, update and completion contract lives in the optional extended protocol reference. The machine-readable GET above is the complete interoperable path for this README.

After payment: status and delivery

If you retained poll_url, fetch it after payment and always continue with the newest poll_url returned. Do not reuse a cached pre-payment response.

• requires_escalationPayment has not yet been observed. Wait for the human; do not claim failure.
• complete_in_progressPayment is confirmed and the eSIM is being issued.
• completedReturn qr_code_url, lpa, smdp_address, matching_id and the permanent order URL.
• canceledRead and report messages[]. A delivery failure after payment is refunded automatically.

Link-only fallback: if you never obtained poll_url, the payment return page—not your chat—shows the QR. Say this before handing off.

Tell the human before purchase

• The phone must support eSIM and be carrier-unlocked.
• Unless validity_starts says otherwise, validity begins on first network connection, not at purchase.
• Install over Wi-Fi before travel. Most profiles can be installed only once.
• Plans are data-only unless voice or SMS fields explicitly say otherwise.
• Installed or used plans are normally non-refundable. Keep the permanent order URL.
• Never request or accept card details in chat. The human pays on hosted Stripe.

Safety, guarantees and advanced reference

• Price, currency and availability are authoritative on the server. Query parameters cannot lower the charge.
• Mutating ACP requests require Idempotency-Key; safe retries do not silently create a second order.
• If payment succeeds but the eSIM cannot be issued, the charge is refunded automatically.
• No customer account, seller API key or plugin is required for the hosted Stripe path.

• https://esimian.com/agent-guide/checkout-v2.txtExtended protocol reference. Optional for the normal buying flow described here.
• https://esimian.com/.well-known/agent.jsonCapability manifest and checkout templates.
• https://esimian.com/healthzLive checkout, provider and fulfilment switches.
• https://esimian.com/supportSupport. Quote the order number and ICCID.

Stripe Shared Payment Token support is optional and currently not advertised. It is not needed for the hosted checkout flow above.

Minimal human invocation

This prompt intentionally points only at the canonical homepage: