Quartermaster eSIM

Read the store's rules as machine-readable JSON before you spend. Use it to learn refund and dispute terms, mandate and registration caps, supplier trust and the quote lifetime. Returns every policy (mandate, refund, dispute, supplier trust, registration), the store terms and the product and agent JSON Schemas. Read-only and free; it takes only agent_id and principal_id (no agent_key) and nothing is charged.

Lock the final price of one plan for a short time before you buy it. Use it after search_plans, with a product id from its results, and before purchase. Returns quote (quote_id, product, price, expires_at), mandate_precheck and wallet_precheck (will the purchase be allowed and funded), refund_terms and a next-step hint. It creates a quote but charges nothing and holds no funds; the lock lasts quote_ttl_seconds (see get_policies) and one quote buys once. Example: {product_id: "wh1-5838281"}.

Create a hosted payment URL to hand to your human principal when the wallet is short. Use it after WALLET_INSUFFICIENT_FUNDS or a low get_wallet balance, then poll get_wallet until the credit appears. Returns the top-up record with its payment URL; it charges nothing by itself. Example: {amount_minor: 2000, currency: "USD"} asks for a 20.00 USD credit. They pay in ILS on the acquirer's page (PayPlus); you never see card data. amount_minor is in `currency`: USD (the wallet credit you want; the ILS charge is computed at today's rate) or ILS (the exact charge). The wallet is credited in USD at the rate in force when payment is confirmed. Limits are in the topup policy.

Check the prepaid USD wallet of the principal you act for. Use it before get_quote or purchase to confirm funds, and after handing a top-up link to your principal to see it credited. Read-only. Returns balance, available funds (balance minus pending holds), open (unpaid) top-up links, top-ups awaiting confirmation, recent top-ups and recent ledger entries of the wallet of the principal you act for. Shared by all of the principal's agents. Amounts in minor units. topups_awaiting_confirmation: a payment was reported for these and is being confirmed with the payment provider; never send their links again, the balance updates once it is confirmed. frozen and debt: a top-up reversed by the payment provider (refund, cancellation, chargeback) is taken back from the balance; what the balance could not cover is a debt that blocks purchases until a top-up settles it. principal.partner_id: the partner the principal was attributed to at registration, if any.

List every agent registered for your principal. Use it to audit who can spend from the shared wallet, to find a target_agent_id for revoke_agent or renew_mandate, or to check a mandate before it expires. Returns, per agent: agent_id, created_at, principal_key_version, status (active, expired or revoked), mandate_expiry and limits, plus active_agents against max_agents_per_principal. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). An agent you do not recognise may have been registered with a leaked principal_key: revoke it, or rotate the key.

Look up one order. Use it after purchase to confirm delivery and read the activation code, whenever a purchase returned status processing, and to check data usage. Read-only. Example: {order_id: "ord_..."}. Returns the current order state, eSIM delivery payload, activation and data usage from the supplier, receipts, and the latest disputes (disputes_total counts all). Any agent of the order's principal may call it (and regenerate_activation and request_refund) for the order; other principals get ORDER_NOT_FOUND.

Buy the plan in a quote and receive the eSIM. Use it after get_quote, before the quote expires and only when mandate_precheck allows it. Returns the order (status, and the eSIM delivery payload with the activation code or QR/LPA) and a signed receipt, and debits the principal's USD wallet. Example: {quote_id: "qt_...", idempotency_key: "<a new UUID>"}. Details: it enforces the mandate and the wallet policy, holds the amount in the principal's wallet, orders from the supplier, debits the wallet, and returns the order with the eSIM delivery payload and a signed receipt. If the wallet is short, fails with WALLET_INSUFFICIENT_FUNDS and a ready top-up link for the principal. idempotency_key is required: reusing it returns the original order and never charges twice; while the original call is still running it answers ORDER_IN_PROGRESS (retryable, retry_after_seconds, order_id: repeat the same call later or poll order_status). QUOTE_PRICE_CHANGED (retryable): the plan's price went up since the quote (error.details.quoted_price and current_price); nothing was held or charged, get a new quote. If the supplier's answer is unknown (timeout, network error), the order stays "processing" with supplier_outcome "unknown" and the price held, not debited: poll order_status and do not buy again with a new key. Only SUPPLIER_FAILURE with retryable=true calls for a new quote and key. PRINCIPAL_FROZEN (not retryable): a top-up was reversed after its credit was spent, or the operator froze the principal; get_topup_link still works and the next credit settles the debt first.

Get a fresh eSIM activation code (QR / LPA) for a delivered order whose code will not install. Use it after the troubleshoot steps fail, before opening a dispute. It works for any order of your principal (bought by any of its agents): it asks the supplier for a fresh code and returns the new delivery payload. Example: {order_id: "ord_..."}. The previous code may stop working. Not every supplier supports it (NOT_SUPPORTED_BY_SUPPLIER); then open a dispute with reason not_working.

Create your agent identity, bound to a principal (the wallet owner), with a spending mandate: the first call to make in this store. Use it when you have no agent_key yet, or to add another agent for a principal you already have. Returns agent_key once (store it and send it on every later call) and, for a brand-new principal_id, principal_key once. Example: {agent_id: "trip-planner-1", principal_id: "principal:acme", mandate: {max_per_tx: 3000, max_per_day: 6000, max_per_month: 20000, expiry: "2027-01-01T00:00:00Z"}} lets the agent spend up to 30.00 USD per purchase. Details: The first agent of a new principal_id also receives principal_key (once): the principal owns the wallet, and every later register_agent for that principal_id must present principal_key (argument or X-Principal-Key header), else PRINCIPAL_KEY_REQUIRED. New agents are capped by the registration policy (see get_policies); only active agents (not revoked, mandate unexpired) count toward max_agents_per_principal. To extend or change an existing agent's mandate, use renew_mandate. Agents brought by a partner of the store also send partner_id and partner_key (both or neither): a new principal is attributed to that partner for good. Invalid partner credentials give PARTNER_INVALID; an existing principal keeps the attribution it was created with (PARTNER_MISMATCH for another partner, PARTNER_ATTRIBUTION_LOCKED if it has none). Attribution changes nothing about prices or limits.

Extend or change an existing agent's spending limits and expiry without registering a new agent. Use it on MANDATE_EXPIRED or to raise or lower limits. It re-signs the mandate of an agent of your principal (you, unless target_agent_id names another) with new limits and expiry, under the same registration policy caps as register_agent. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). The agent keeps its agent_id, agent_key and spend history. Use it on MANDATE_EXPIRED or to change limits instead of registering a new agent; an agent whose mandate had expired takes a slot again (PRINCIPAL_AGENT_LIMIT when none is free). Revoked agents cannot be renewed (AGENT_REVOKED).

Ask for a refund, or open a dispute, on an order. Use it when an eSIM went unused or plans changed (voluntary refund), or when it was not delivered, does not work or was bought twice (dispute). Example: {order_id: "ord_...", reason: "not_working", details: "QR installs, no data after restart, iPhone 15 on iOS 17"}. Returns the decision {allowed, reason_code, human_readable} and, when credited, the refund to the wallet. Reasons "unused" and "changed_plans" are voluntary refunds under the refund policy. Reasons "not_delivered", "not_working" and "duplicate_purchase" open a dispute under the dispute policy, which can refund fully, partially, reject, or escalate to a human. A dispute about a delivered eSIM is credited automatically only when the supplier confirms it cancelled the eSIM; otherwise, and for partial refunds, it is escalated (outcome "escalate", reason DISPUTE_SUPPLIER_CANCEL_UNCONFIRMED). Orders the supplier has not confirmed yet are refused with ORDER_AWAITING_SUPPLIER (poll order_status). An order takes one escalated dispute at a time (DISPUTE_ALREADY_OPEN until a human decides it) and a limited number of disputes in all (DISPUTE_LIMIT_REACHED). Any agent of the principal that owns the order may ask. ORDER_CHANGED is retryable. After a full refund, order_status no longer returns the activation code. Denials return error.code = the policy reason_code.

Disable one agent of your principal permanently. Use it when an agent is unknown, compromised or no longer needed; it frees its slot. After this it can no longer authenticate (AGENT_REVOKED) and no longer holds a slot under max_agents_per_principal. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). Its orders stay visible to the principal's other agents. Repeating it changes nothing (already_revoked).

Replace your principal's principal_key and cut off every agent that should not keep access. Use it when the key may have leaked or when you want to revoke a group of agents at once. Returns the new key once. Needs your agent credentials and the current principal_key (argument or X-Principal-Key header). Returns the new key once; the old one stops working. Every agent registered under the previous key is revoked for good (AGENT_REVOKED) except you and the agents in keep_agent_ids (list_agents shows them); the result lists kept_agent_ids and revoked_agent_ids. A principal registered before keys existed has none: any of its agents can call this without principal_key to mint the first one, which revokes nobody.

Sandbox only. Marks the order's eSIM as installed and used, as if the traveler activated it. Use it to exercise refund and dispute rules.

Sandbox only. Acts as the principal paying a get_topup_link URL: the mock provider sends a PayPlus-format IPN through the same webhook path production uses, and the wallet is credited. outcome "declined" simulates a failed card.

Find eSIM data plans for a destination, with final prices in minor units. Use it first, when a traveler needs mobile data abroad: filter by country (ISO code), region, minimum data, validity and price, then compare. Returns results (each with id, title, countries, regions, data_gb or "unlimited", validity_days, price_final {amount_minor, currency, tax_included}, availability, delivery, refund_rule and constraints such as hotspot, network types and operators), total_matches, sort and excluded_suppliers. Defaults: in-stock plans only, cheapest first, 10 results. Read-only and free; pass a result's id to get_quote. Suppliers below the trust threshold are excluded and listed in excluded_suppliers. Example: {country: "JP", min_data_gb: 5, max_validity_days: 30, sort: "price"}.

Get step-by-step fixes to relay to the traveler when an eSIM will not install or has no data. Use it when a delivered order's traveler reports a problem, before regenerate_activation or request_refund. Example: {order_id: "ord_...", device: {os: "ios", model: "iPhone 15"}, symptom: "no_data"}. Returns ordered steps for an order's eSIM that does not install (cant_install_qr) or does not work (no_data, no_signal, slow), worded for the phone (device.os ios or android, device.model if known): eSIM compatibility and carrier lock, install by QR or manual entry (SM-DP+ address and activation code), data roaming on the eSIM line, the eSIM as the data line, the APN when the plan has one, airplane-mode toggle and restart, then the escalation (regenerate_activation, request_refund with reason not_working and the evidence to include, or order_status for a code not delivered yet). Also returns the order's status and the plan's APN, networks and network types (plan_facts); activation and usage only as the supplier reports them. Read-only: it reissues nothing and opens no dispute. Any agent of the order's principal may call it; other principals get ORDER_NOT_FOUND. A refunded or failed order gets no steps.

Check that a purchase receipt is genuine. Use it when you or your principal need proof of what was bought and paid. Pass the receipt object exactly as purchase or order_status returned it. Returns whether the receipt's signature is valid and whether it matches its entry in the store's hash-chained ledger. Read-only; nothing is changed or charged.