varioroam eSIM configurator

What varioroam is and how it works, in the shop’s own words: the configurable eSIM, ranges, delivery, payment, hotspot, activation, top-ups (add data or days), e-mails, support. Use for any question that is not a price.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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."
    }
  }
}

Every country varioroam can build an eSIM for, with the number of selectable networks and the starting price (1 GB, 1 day, cheapest network). Use to check coverage or to compare many countries at once.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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."
    }
  }
}

The mobile networks the customer can tick for one country (operator name, 4G/5G) with the price of a reference eSIM on each network alone (1 GB · 7 days), so you can say which network is the cheapest and what the others add.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per eSIM."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "destination"
  ]
}

Use while the customer is still deciding — "how much is …?": the exact price of one eSIM configuration (country, data GB 1–100, days 1–90, networks), the server price the customer would pay. Quote it as returned, never compute or scale it yourself. The result carries a buy_url for reference; when the customer says they want to buy, call start_checkout instead.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per eSIM."
    },
    "gb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Data pool in whole GB for the whole trip (1–100). One pool, not per day. Not sure how much? Call recommend_config."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "description": "Validity days (1–90)."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional: operator names (or codes) from get_networks to include. Omit = the cheapest network of the country. The dearest included network sets the data price and every network beyond the first adds a small fee."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "destination",
    "gb",
    "days"
  ]
}

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Resolved country name (localized)."
    },
    "iso": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2, lower case."
    },
    "data_gb": {
      "type": "integer",
      "description": "Total data pool for the whole validity (whole GB). Not per day."
    },
    "days": {
      "type": "integer",
      "description": "Validity in days, counted from the first connection at the destination."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Operator names included in this eSIM."
    },
    "price": {
      "type": "number",
      "description": "FULL price of this configuration in currency — the amount paid. Not per day, not per GB."
    },
    "currency": {
      "type": "string"
    },
    "price_basis": {
      "type": "string",
      "enum": [
        "total"
      ]
    },
    "price_is_final": {
      "type": "boolean"
    },
    "hotspot": {
      "type": "boolean"
    },
    "activation_trigger": {
      "type": "string"
    },
    "topup": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "data_days"
          ]
        },
        "how": {
          "type": "string"
        }
      },
      "description": "How the customer adds data or days to this eSIM later (not through the tools)."
    },
    "networks_unmatched": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Present when a requested network does not exist in this country: those names. The quote then uses the networks listed in networks."
    },
    "note": {
      "type": "string",
      "description": "Present when something about the request had to be adjusted — read it to the customer."
    },
    "buy_url": {
      "type": "string",
      "description": "Configurator pre-set to exactly this configuration. Use verbatim."
    }
  },
  "additionalProperties": true
}

Prices for several GB × days combinations of one country in one call (max 8 × 8), e.g. to compare with other providers or to find the best fit for a trip. Same server prices as quote_esim.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per eSIM."
    },
    "gb": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "minItems": 1,
      "maxItems": 8,
      "description": "Up to 8 whole-GB values, e.g. [1,3,5,10,20]."
    },
    "days": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 90
      },
      "minItems": 1,
      "maxItems": 8,
      "description": "Up to 8 day values, e.g. [3,7,15,30]."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional: operator names (or codes) from get_networks to include. Omit = the cheapest network of the country. The dearest included network sets the data price and every network beyond the first adds a small fee."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "destination",
    "gb",
    "days"
  ]
}

Use when the customer describes a trip instead of a size: country (or up to 5), days and how they use data (usage light / normal / heavy, or gb_per_day). Sizes the data pool from the data guide and returns three server-quoted configurations per country — exact, comfortable (×1.5) and generous (×2) — each with its price, networks, a one-line reason and its buy_url, plus trip totals and an optional budget check. Prices are the same as quote_esim.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per eSIM."
    },
    "destinations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 5,
      "description": "Several countries (max 5), any language or ISO codes. Use instead of destination for a multi-country trip."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "description": "Days of the trip (per country for a multi-country trip; 1–90)."
    },
    "usage": {
      "type": "string",
      "enum": [
        "light",
        "normal",
        "heavy"
      ],
      "description": "light ≈ 0.5 GB/day, normal ≈ 1.5 GB/day (default), heavy ≈ 4 GB/day."
    },
    "gb_per_day": {
      "type": "number",
      "minimum": 0.1,
      "maximum": 100,
      "description": "Optional: the customer's own estimate in GB per day (wins over usage)."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional: operator names (or codes) from get_networks to include. Omit = the cheapest network of the country. The dearest included network sets the data price and every network beyond the first adds a small fee."
    },
    "budget": {
      "type": "number",
      "description": "Optional budget for the whole trip in the quoted currency; options above it are marked."
    },
    "per_country": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "destination": {
            "type": "string"
          },
          "days": {
            "type": "integer"
          }
        }
      },
      "description": "Optional days per country for a multi-country trip."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "days"
  ]
}

A trip through several countries (max 5): one eSIM per country, each quoted with the same data pool and days unless given per country (gb omitted = sized for normal use from the days). Returns one line per country with price and buy_url, plus the total. Use when the customer names more than one country and a size; use recommend_config when they describe usage instead.

{
  "type": "object",
  "properties": {
    "destinations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 5,
      "description": "Countries of the trip, any language or ISO codes, in travel order."
    },
    "gb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Data pool per country in whole GB (1–100). Omit = sized for normal use from the days (1.5 GB/day)."
    },
    "days": {
      "type": "integer",
      "description": "Validity days per country (1–90). Default 7."
    },
    "per_country": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "destination": {
            "type": "string"
          },
          "gb": {
            "type": "number"
          },
          "days": {
            "type": "integer"
          }
        }
      },
      "description": "Optional overrides per country (gb and/or days)."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "destinations"
  ]
}

Use only once the customer has decided to buy ("I'll take it", "how do I buy?"): the checkout handoff. Returns the buy_url to give the customer, the final price and a ready-to-send checkout block (next_step, payment_methods, delivery) — on the page they press "Get it" and pay 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": {
    "destination": {
      "type": "string",
      "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per eSIM."
    },
    "gb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Data pool in whole GB (1–100)."
    },
    "days": {
      "type": "integer",
      "description": "Validity days (1–90)."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional: operator names (or codes) from get_networks to include. Omit = the cheapest network of the country. The dearest included network sets the data price and every network beyond the first adds a small fee."
    },
    "language": {
      "type": "string",
      "description": "ISO language of the conversation, e.g. en, de, ja. Localizes country 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"
    }
  },
  "required": [
    "destination",
    "gb",
    "days"
  ]
}

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Resolved country name (localized)."
    },
    "iso": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2, lower case."
    },
    "data_gb": {
      "type": "integer",
      "description": "Total data pool for the whole validity (whole GB). Not per day."
    },
    "days": {
      "type": "integer",
      "description": "Validity in days, counted from the first connection at the destination."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Operator names included in this eSIM."
    },
    "price": {
      "type": "number",
      "description": "FULL price of this configuration in currency — the amount paid. Not per day, not per GB."
    },
    "currency": {
      "type": "string"
    },
    "price_basis": {
      "type": "string",
      "enum": [
        "total"
      ]
    },
    "price_is_final": {
      "type": "boolean"
    },
    "hotspot": {
      "type": "boolean"
    },
    "activation_trigger": {
      "type": "string"
    },
    "topup": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "data_days"
          ]
        },
        "how": {
          "type": "string"
        }
      },
      "description": "How the customer adds data or days to this eSIM later (not through the tools)."
    },
    "networks_unmatched": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Present when a requested network does not exist in this country: those names. The quote then uses the networks listed in networks."
    },
    "note": {
      "type": "string",
      "description": "Present when something about the request had to be adjusted — read it to the customer."
    },
    "buy_url": {
      "type": "string",
      "description": "Configurator pre-set to exactly this configuration. Use verbatim."
    },
    "next_step": {
      "type": "string",
      "description": "What the customer does now: open buy_url, press \"Get it\", 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
}