worldwide eSIM — one eSIM for the whole world

What worldwide eSIM is and how it works, in the shop’s own words: one mobile-data eSIM for the whole world or chosen continents, one data pool, validity (until the data is used up, up to 180 days from the first connection), recharge, delivery, installation, devices, payment, refunds, My eSIM, e-mails, support. Use for any question that is not a price or a country.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    }
  }
}

The five continents with their number of countries and the starting price of each (the smallest data size for that continent alone) plus the whole world. Pass continent to list its countries (continent "world" lists every country); include_networks adds the operator names and a 5G flag per country. Use to show where the eSIM works.

{
  "type": "object",
  "properties": {
    "continent": {
      "type": "string",
      "enum": [
        "eu",
        "as",
        "am",
        "af",
        "oc",
        "world"
      ],
      "description": "Optional: list the countries of this continent (eu, as, am, af, oc) or of the whole world (\"world\")."
    },
    "include_networks": {
      "type": "boolean",
      "description": "Optional: with continent, add the mobile networks (operator name + 5G flag) of each country."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  }
}

Is one country included? Pass its name in any language or its ISO-2 code (map a city to its country first). Returns included true/false, the continent, the mobile networks (operator names + 5G flag) and the cheapest coverage choice that includes it (its continent alone) with the server price and buy_url, plus the whole world at the same size for comparison.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\"."
    },
    "gb": {
      "type": "integer",
      "enum": [
        3,
        5,
        10,
        20,
        30,
        50,
        100
      ],
      "description": "The data pool in GB, ONE pool for every included country: 3, 5, 10 (more: 20, 30, 50, 100). Omit = 3 GB. Not sure? Call recommend_config."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  },
  "required": [
    "country"
  ]
}

Use while the customer is still deciding — "how much is …?": the exact server price of ONE worldwide eSIM for the chosen continents (default: the whole world) and data size — the amount the customer would pay — with the number of countries, the validity (until the data is used up, up to 180 days), hotspot, the recharge options and prices, and a buy_url for reference. Quote the price as returned; never compute or scale it. When the customer says they want to buy, call start_checkout.

{
  "type": "object",
  "properties": {
    "continents": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "eu",
          "as",
          "am",
          "af",
          "oc"
        ]
      },
      "minItems": 1,
      "maxItems": 5,
      "uniqueItems": true,
      "description": "Continents to cover: eu (Europe), as (Asia & Middle East), am (Americas), af (Africa), oc (Oceania). Omit = the whole world (all five). Fewer continents can lower the price. A country is not a continent — use check_country or recommend_config for countries."
    },
    "gb": {
      "type": "integer",
      "enum": [
        3,
        5,
        10,
        20,
        30,
        50,
        100
      ],
      "description": "The data pool in GB, ONE pool for every included country: 3, 5, 10 (more: 20, 30, 50, 100). Omit = 3 GB. Not sure? Call recommend_config."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  }
}

{
  "type": "object",
  "properties": {
    "coverage": {
      "type": "object",
      "additionalProperties": true,
      "description": "The chosen continents.",
      "properties": {
        "continents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "countries": {
                "type": "integer"
              }
            }
          }
        },
        "whole_world": {
          "type": "boolean"
        },
        "label": {
          "type": "string",
          "description": "\"Whole world\" or the continents joined with +, localized."
        }
      }
    },
    "countries": {
      "type": "integer",
      "description": "Number of countries included."
    },
    "data_gb": {
      "type": "integer",
      "description": "ONE data pool for every included country (not per day, not per country)."
    },
    "validity": {
      "type": "string",
      "description": "\"until the data is used up, up to 180 days\" — say it this way."
    },
    "valid_days_max": {
      "type": "integer"
    },
    "validity_starts": {
      "type": "string",
      "enum": [
        "first_connection"
      ],
      "description": "The days start at the first connection to a network, not at purchase or installation."
    },
    "price": {
      "type": "number",
      "description": "FULL price of exactly this choice in currency — the amount paid. Not per GB, per day or per country."
    },
    "currency": {
      "type": "string"
    },
    "price_basis": {
      "type": "string",
      "enum": [
        "total"
      ]
    },
    "price_is_final": {
      "type": "boolean"
    },
    "hotspot": {
      "type": "boolean"
    },
    "data_only": {
      "type": "boolean",
      "description": "true: no phone number, no SMS."
    },
    "topup": {
      "type": "object",
      "additionalProperties": true,
      "description": "How the customer recharges later (+1, +3 or +10 GB, renews the validity), with the server recharge prices for this coverage when available.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "recharge"
          ]
        },
        "options_gb": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "how": {
          "type": "string"
        },
        "prices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "data_gb": {
                "type": "integer"
              },
              "price": {
                "type": "number"
              }
            }
          }
        }
      }
    },
    "continents_unmatched": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Requested values that are not a continent (left out of the quote)."
    },
    "note": {
      "type": "string",
      "description": "Present when something about the request had to be adjusted — read it to the customer."
    },
    "buy_url": {
      "type": "string",
      "description": "The shop page preset to exactly this choice. Use verbatim."
    },
    "coverage_url": {
      "type": "string",
      "description": "Every included country and network by continent."
    }
  },
  "additionalProperties": true
}

Every data size (or the sizes asked for) for one coverage choice in one call, each with the server price and its own buy_url; with compare_continents also the whole world against each single continent — to show what a smaller coverage saves. Same server prices as quote_esim.

{
  "type": "object",
  "properties": {
    "continents": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "eu",
          "as",
          "am",
          "af",
          "oc"
        ]
      },
      "minItems": 1,
      "maxItems": 5,
      "uniqueItems": true,
      "description": "Continents to cover: eu (Europe), as (Asia & Middle East), am (Americas), af (Africa), oc (Oceania). Omit = the whole world (all five). Fewer continents can lower the price. A country is not a continent — use check_country or recommend_config for countries."
    },
    "gb": {
      "type": "array",
      "items": {
        "type": "integer",
        "enum": [
          3,
          5,
          10,
          20,
          30,
          50,
          100
        ]
      },
      "maxItems": 7,
      "description": "Optional: the sizes to price. Omit = every size (3, 5, 10, 20, 30, 50, 100)."
    },
    "compare_continents": {
      "type": "boolean",
      "description": "Optional: also price the whole world and each continent alone."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  }
}

Use when the customer names the countries of a trip instead of continents and a size: returns the smallest set of continents that covers every named country (countries that are not included come back in not_covered), a suggested data size from the days and usage (light ≈ 0.5 GB/day, normal ≈ 1.5, heavy ≈ 4; rounded up to the next size) and server quotes for that size and one size down and up, each with its buy_url, plus the whole world at the suggested size. Same prices as quote_esim.

{
  "type": "object",
  "properties": {
    "countries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 30,
      "description": "The countries of the trip, names in any language or ISO-2 codes, e.g. [\"Japan\", \"Thailand\", \"Australia\"]. Map cities to their countries first."
    },
    "usage": {
      "type": "string",
      "enum": [
        "light",
        "normal",
        "heavy"
      ],
      "description": "light ≈ 0.5 GB/day (messaging, maps, mail), normal ≈ 1.5 GB/day (default; social media, music, some video), heavy ≈ 4 GB/day (video streaming, video calls, hotspot for a laptop)."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Optional: days the customer will use mobile data. Without days the size follows the usage alone (light 3 / normal 5 / heavy 10 GB)."
    },
    "gb_per_day": {
      "type": "number",
      "minimum": 0.1,
      "maximum": 50,
      "description": "Optional: the customer's own estimate in GB per day (wins over usage)."
    },
    "budget": {
      "type": "number",
      "description": "Optional budget in the quoted currency; options above it are marked."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  },
  "required": [
    "countries"
  ]
}

Use only once the customer has decided to buy ("I'll take it", "how do I buy?"): the checkout handoff for one choice (same input as quote_esim). Returns the buy_url to give the customer, the final price and a ready-to-send checkout block (next_step, payment_methods, delivery) — the shop page opens preset to exactly this coverage and size; the customer presses "Get your eSIM" and pays securely. No account needed; the eSIM is delivered on screen and by e-mail right after payment. No in-chat order tracking, no discount codes. For prices while the customer is still comparing, use quote_esim.

{
  "type": "object",
  "properties": {
    "continents": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "eu",
          "as",
          "am",
          "af",
          "oc"
        ]
      },
      "minItems": 1,
      "maxItems": 5,
      "uniqueItems": true,
      "description": "Continents to cover: eu (Europe), as (Asia & Middle East), am (Americas), af (Africa), oc (Oceania). Omit = the whole world (all five). Fewer continents can lower the price. A country is not a continent — use check_country or recommend_config for countries."
    },
    "gb": {
      "type": "integer",
      "enum": [
        3,
        5,
        10,
        20,
        30,
        50,
        100
      ],
      "description": "The data pool in GB, ONE pool for every included country: 3, 5, 10 (more: 20, 30, 50, 100). Omit = 3 GB. Not sure? Call recommend_config."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country and continent names and sets the language/currency of links and prices."
    },
    "bucket": {
      "type": "string",
      "description": "Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."
    },
    "currency": {
      "type": "string",
      "description": "Optional ISO 4217 override for prices."
    }
  }
}

{
  "type": "object",
  "properties": {
    "coverage": {
      "type": "object",
      "additionalProperties": true,
      "description": "The chosen continents.",
      "properties": {
        "continents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "countries": {
                "type": "integer"
              }
            }
          }
        },
        "whole_world": {
          "type": "boolean"
        },
        "label": {
          "type": "string",
          "description": "\"Whole world\" or the continents joined with +, localized."
        }
      }
    },
    "countries": {
      "type": "integer",
      "description": "Number of countries included."
    },
    "data_gb": {
      "type": "integer",
      "description": "ONE data pool for every included country (not per day, not per country)."
    },
    "validity": {
      "type": "string",
      "description": "\"until the data is used up, up to 180 days\" — say it this way."
    },
    "valid_days_max": {
      "type": "integer"
    },
    "validity_starts": {
      "type": "string",
      "enum": [
        "first_connection"
      ],
      "description": "The days start at the first connection to a network, not at purchase or installation."
    },
    "price": {
      "type": "number",
      "description": "FULL price of exactly this choice in currency — the amount paid. Not per GB, per day or per country."
    },
    "currency": {
      "type": "string"
    },
    "price_basis": {
      "type": "string",
      "enum": [
        "total"
      ]
    },
    "price_is_final": {
      "type": "boolean"
    },
    "hotspot": {
      "type": "boolean"
    },
    "data_only": {
      "type": "boolean",
      "description": "true: no phone number, no SMS."
    },
    "topup": {
      "type": "object",
      "additionalProperties": true,
      "description": "How the customer recharges later (+1, +3 or +10 GB, renews the validity), with the server recharge prices for this coverage when available.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "recharge"
          ]
        },
        "options_gb": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "how": {
          "type": "string"
        },
        "prices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "data_gb": {
                "type": "integer"
              },
              "price": {
                "type": "number"
              }
            }
          }
        }
      }
    },
    "continents_unmatched": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Requested values that are not a continent (left out of the quote)."
    },
    "note": {
      "type": "string",
      "description": "Present when something about the request had to be adjusted — read it to the customer."
    },
    "buy_url": {
      "type": "string",
      "description": "The shop page preset to exactly this choice. Use verbatim."
    },
    "coverage_url": {
      "type": "string",
      "description": "Every included country and network by continent."
    },
    "next_step": {
      "type": "string",
      "description": "What the customer does now: open buy_url, press \"Get your eSIM\", pay."
    },
    "payment_methods": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "delivery": {
      "type": "string",
      "description": "How and when the eSIM arrives."
    },
    "message": {
      "type": "string",
      "description": "A ready-to-send line for the customer."
    }
  },
  "required": [
    "buy_url",
    "price",
    "currency",
    "next_step"
  ],
  "additionalProperties": true
}