doctorSIM Agentic Commerce

Gift card denominations for a brand (id_operator from get_giftcard_brands) with token (use as price_token), service fee, and total per price point. Then preview_order / create_order with price_token only — never send a phone for gift cards.

List gift card brands (gaming, streaming, retail) for a country — no phone number involved. Each brand is an id_operator; pass it to get_giftcard_brand_products for denominations and price tokens. Paginated: pass cursor=meta.cursor when meta.has_more is true.

Get live pricing for an operator. Each rate has product_name, description (bundle/data details), and token for preview_order/create_order. Use operator_id from get_operator_service_types for the chosen type (bundle vs airtime vs data). Pass q to search descriptions (e.g. q="5GB whatsapp"). Rate totals are indicative — call preview_order for the authoritative breakdown before the user confirms.

After carrier lookup, list what recharge types are available for an operator: airtime (saldo), bundles, mobile data, etc. Each type has its own id_operator — use that id for get_operator_rates. Ask the user: "Do you want airtime, bundles, or data?" then call rates with the matching service type.

List mobile operators for a country (uses id_country from get_countries). Use when carrier lookup failed or the user already knows the operator.

Check order or checkout status. Guests: pass payment_link (preferred) or checkout_hash from create_order — no login; the hash is unguessable. Do not pass a sequential order_id without OAuth (IDs are enumerable). Do not ask the buyer for the hash or show it. OAuth / PRO: pass order_id (sandbox orders: sandbox_… id). If create_order timed out before returning order_id, pass its idempotency_key instead — never re-create. Fulfilled eSIM orders include iccid, lpa_string, install_url, a hosted qr_code_url PNG, remaining balance_amount (provider refresh only when last check is older than five minutes), and nested consumption (cron snapshot: activated, unlimited, data_remaining_gb, days_left). Fulfilled gift cards may include redemption_code or redemption_url.

Guest order status when checkout_hash is gone. Pass the buyer email and the user-visible ticket (order_id). No login. Wrong email or wrong ticket both return generic ORDER_NOT_FOUND. Prefer get_order_status with payment_link when the hash is still known. Sequential GET /orders/{id} still requires OAuth.

List completed or refunded orders for the authenticated user. Requires OAuth — not available for guest checkout. type=esim includes iccid, install_url, and hosted qr_code_url on fulfilled rows. balance_amount is "per order basis" on the list (no provider call). Decode nested consumption for days left / remaining data / unlimited (cron snapshot).

PRO accounts only (requires webhooks:read OAuth scope). Lists registered webhook subscriptions. Requires OAuth.

Identify the mobile carrier (operator) and country from a phone number in E.164 format (e.g. +522221231231). ALWAYS call this FIRST when the user provides a phone number for a top-up. Returns id_operator and id_country for the next steps. If lookup fails, ask the user which carrier/network the number uses.

Alias of preview_order with type=esim (kept for existing connectors). Guest can call this without Authorization (same as preview_order). Preview a travel eSIM order without placing it (no credits deducted). Returns unlimited (boolean), data_gb, and checkout_mode (credits for PRO, payment_link for guest / consumer OAuth). Sandbox keys (test_*) use the sandbox catalog.

Returns the price breakdown WITHOUT placing an order — one tool for every vertical (top-up, gift card, travel eSIM; type is inferred from price_token / catalog_id). Guest (no login) gets checkout_mode=payment_link — show amount_due_eur; OAuth PRO gets checkout_mode=credits with credit applied. Travel eSIM (catalog_id + price_token from get_esim_plans) also returns unlimited and data_gb. Call once after product selection, then confirm before create_order.

Browse the country catalog by operator/brand name (gift cards, gaming, etc.). For mobile top-ups with a phone number, use lookup_carrier first, then get_operator_service_types and get_operator_rates — NOT this tool alone. When operator_id AND q are both set, searches live rate descriptions (bundles/data) for that operator instead of catalog names. Paginated: pass cursor=meta.cursor when meta.has_more is true.