Hungry eSIM

Search prepaid travel eSIM data plans for a destination — the SIM card / mobile data / roaming option for a trip. Use this first for any "data plan for my trip to X" request. Includes unlimited plans where the traveller picks the number of days, and fixed-data plans. Filter by unlimited vs fixed-data, minimum data, and validity. Unlimited plans are quoted per day, fixed-data plans as a one-off total — never compare those two numbers directly. The unlimited total is the per-day price × days, with a volume discount from 7 days, so pass days (trip length) to get that total quoted alongside the daily rate. Price differences between similar plans come from the routing IP country (routing_ip_country) and the supported networks (speed) — quote both when comparing plans. Results are grouped: fixed-data plans first, then unlimited; each group sorted by price. Returns variant_id values to pass to create_checkout.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO 3166-1 alpha-2 country code, e.g. 'JP', 'US'",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "unlimited": {
      "description": "If set, return only unlimited (true) or only fixed-data (false) plans",
      "type": "boolean"
    },
    "min_data_gb": {
      "description": "Minimum data in GB (fixed-data plans)",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "max_validity_days": {
      "description": "Maximum validity in days (fixed-data plans)",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "days": {
      "description": "Trip length in days (1-30, the range an unlimited plan can be bought for). When given, unlimited plans also quote the total for that many days, multi-day discount included.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "currency": {
      "description": "ISO currency for prices, default USD",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "limit": {
      "description": "Max results, default 10",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "country"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get everything about one eSIM data plan: which countries the SIM roams in, data volume, validity in days, speed and fair-use throttling, and price. Use after search_esim_plans or find_cheapest_plan when the traveller asks what exactly a plan includes before buying.

{
  "type": "object",
  "properties": {
    "variant_id": {
      "description": "Variant id from search_esim_plans",
      "type": "string"
    },
    "currency": {
      "description": "ISO currency, default USD",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "required": [
    "variant_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Buy the chosen eSIM data plan: builds a cart and returns a checkout URL the traveller opens to pay by credit card on hungry-esim.com — no crypto wallet and no API key needed. Use once a plan is picked. Does NOT charge — the user completes payment on the website. For unlimited plans, period_num (how many days of data the traveller wants) is required. If the customer is signed in, the order is linked to their account automatically.

{
  "type": "object",
  "properties": {
    "variant_id": {
      "description": "Variant id from search_esim_plans",
      "type": "string"
    },
    "country": {
      "description": "Customer's CHECKOUT country (ISO alpha-2) — sets checkout region/currency and URL locale. NOT the eSIM's coverage country. If the store doesn't serve it, the store's default region is used.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "count": {
      "description": "Number of eSIMs, default 1",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "period_num": {
      "description": "Days for unlimited plans (1-30). Required for unlimited, ignored otherwise.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "email": {
      "description": "Guest email — prefills checkout so it skips the details step. Ignored when the customer is signed in (their account email is used). Never determines which account the order belongs to.",
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  },
  "required": [
    "variant_id",
    "country"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up an eSIM order and return its status plus the SIM install details: install link, LPA activation code, QR image URL, and ICCID. Use for "where is my eSIM", "resend my QR code", or "did my order go through" when an order number is known. Signed-in customers can look up their own orders by number without an email. Otherwise, a short order number MUST be paired with the email used for the order — the eSIM install details are only returned to the buyer.

{
  "type": "object",
  "properties": {
    "order": {
      "description": "Order number (e.g. '32') or Medusa order id (order_01K...) from the confirmation email",
      "type": "string"
    },
    "email": {
      "description": "Email used for the order. Required when 'order' is a short order number and the customer is not signed in.",
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  },
  "required": [
    "order"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the SIM cards (eSIMs) already on the signed-in Hungry eSIM account: ICCID, status, data package, expiry, and install link. Use for "my eSIM", "my SIM card", "how much data do I have left", or before topping up a SIM the traveller already owns. Requires connecting the Hungry eSIM account (OAuth) — no API key.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the data top-up (recharge / refill) packages that can be added to an eSIM the customer already owns. Use when the traveller ran out of mobile data or wants more days on a SIM they already bought — topping up reuses the installed SIM, so no new QR code is needed. Pass the ICCID from my_esims. Returns package_code values to pass to topup_esim.

{
  "type": "object",
  "properties": {
    "iccid": {
      "description": "ICCID of the eSIM, from my_esims",
      "type": "string"
    }
  },
  "required": [
    "iccid"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Recharge an eSIM the customer already owns with more data: builds a cart and returns a checkout URL to pay by credit card on hungry-esim.com. The installed SIM keeps working — no new QR code is issued. Use this instead of create_checkout when the traveller already has one of our eSIMs. Does NOT charge — the user completes payment on the website. Get iccid from my_esims and package_code from list_esim_topups.

{
  "type": "object",
  "properties": {
    "iccid": {
      "description": "ICCID of the eSIM to top up, from my_esims",
      "type": "string"
    },
    "package_code": {
      "description": "Top-up package code from list_esim_topups",
      "type": "string"
    },
    "country": {
      "description": "Customer's CHECKOUT country (ISO alpha-2) — sets checkout region/currency and URL locale. Defaults to US.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    }
  },
  "required": [
    "iccid",
    "package_code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the signed-in customer's recent eSIM purchases with payment and provisioning status. Use for "what did I buy" or "did my order go through" when no order number is at hand. For the install QR and activation code of one order, use get_order_status.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check whether we cover a destination before choosing a plan — answers "do you work in X?", "can I get mobile data / a SIM card in X?", "is X supported?". Returns yes/no, how many plans cover it, and the cheapest unlimited and fixed-data plan as examples. Use search_esim_plans or find_cheapest_plan for the full list.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO 3166-1 alpha-2 country code of the destination, e.g. 'JP', 'US'",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "currency": {
      "description": "ISO currency for prices, default the store currency",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "required": [
    "country"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Find the lowest-priced eSIM data plan for a destination — for "what's the cheapest", "budget option", "cheapest SIM / data plan for X". Pass days (trip length) to rank by what the traveller actually pays for the whole trip: unlimited plans are priced per day with a multi-day discount, fixed-data plans by their sticker price, and plans that expire before the trip ends are dropped. Without days it ranks by daily rate. Returns up to 3 options with variant_id for create_checkout.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO 3166-1 alpha-2 country code of the destination, e.g. 'JP', 'US'",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "days": {
      "description": "Trip length in days. When given, plans are ranked by total trip cost.",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    },
    "min_data_gb": {
      "description": "Minimum data in GB (applies to fixed-data plans; unlimited always qualifies)",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "currency": {
      "description": "ISO currency for prices, default the store currency",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "limit": {
      "description": "How many options to return, default 3",
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    }
  },
  "required": [
    "country"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}