{
  "openapi": "3.1.0",
  "info": {
    "title": "eSIMPont plans API",
    "version": "1.0.0",
    "summary": "Every eSIMPont plan that can be bought online, with final VAT-inclusive prices.",
    "description": "Read-only. One API key per partner (x-api-key header); 5 requests per second and 1,000 per day. Documentation and terms of use: https://www.esimpont.hu/en/partners.html",
    "contact": {
      "name": "eSIMPont partnerships",
      "email": "partner@esimpont.hu",
      "url": "https://www.esimpont.hu/en/partners.html"
    },
    "termsOfService": "https://www.esimpont.hu/en/partners.html#terms"
  },
  "servers": [
    {
      "url": "https://ql1gdzweui.execute-api.eu-central-1.amazonaws.com/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/plans": {
      "get": {
        "operationId": "getPlans",
        "summary": "All plans, destinations and prices",
        "parameters": [
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The last ETag you received; answered with 304 if nothing changed."
          }
        ],
        "responses": {
          "200": {
            "description": "The plans document.",
            "headers": {
              "ETag": {
                "description": "Content fingerprint (same as dataVersion). Send it back in If-None-Match.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "private, max-age=3600"
                }
              },
              "Last-Modified": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlansDocument"
                },
                "example": {
                  "apiVersion": 1,
                  "updatedAt": "2026-10-22T16:35:31Z",
                  "dataVersion": "0a7c39d7c287ce38",
                  "schema": "/v1/schema",
                  "provider": {
                    "name": "eSIMPont",
                    "website": "https://www.esimpont.hu/",
                    "contact": "partner@esimpont.hu"
                  },
                  "currencies": [
                    "HUF",
                    "EUR",
                    "RON",
                    "RSD"
                  ],
                  "pricesIncludeVat": true,
                  "esimFee": {
                    "amount": {
                      "HUF": 490,
                      "EUR": 1.36,
                      "RON": 6.94,
                      "RSD": 166.06
                    },
                    "appliesTo": "Purchases that need a new eSIM profile: the traveller's first purchase, or a destination that cannot be loaded onto the eSIM they already have. Top-ups onto an eSIMPont eSIM the traveller already has are exempt.",
                    "waived": null
                  },
                  "planTerms": {
                    "validityStarts": "first data connection at the destination",
                    "activateWithinMonths": 12,
                    "delivery": "QR code by e-mail right after payment",
                    "hotspot": true,
                    "topUps": true,
                    "refund": "The 14-day withdrawal right ends when the QR code is delivered (the buyer consents at checkout). If a fault on our side cannot be fixed, the price is refunded."
                  },
                  "linkParameters": {
                    "plan": "pre-selects a plan on the product page, e.g. ?plan=5gb-15d (already in every plan url)",
                    "ref": "partner code for attribution, e.g. ?ref=CODE (ask us for one); remembered for 30 days",
                    "utm_*": "utm_source / utm_medium / utm_campaign / utm_content are recorded",
                    "currency": "fixed by the page language: hu = HUF, en/de/es/fr/sk = EUR, ro = RON, sr = RSD (see destinations[].localizedUrls)"
                  },
                  "destinations": [
                    {
                      "id": "torokorszag",
                      "name": "Turkey",
                      "type": "country",
                      "countries": [
                        {
                          "iso2": "TR",
                          "name": "Turkey",
                          "networks": [
                            "Turk Telekom Turkey",
                            "Vodafone Turkey"
                          ]
                        }
                      ],
                      "url": "https://www.esimpont.hu/esim-torokorszag.html",
                      "localizedUrls": {
                        "hu": "https://www.esimpont.hu/esim-torokorszag.html",
                        "en": "https://www.esimpont.hu/en/esim-turkey.html",
                        "de": "https://www.esimpont.hu/de/esim-tuerkei.html",
                        "es": "https://www.esimpont.hu/es/esim-turquia.html",
                        "fr": "https://www.esimpont.hu/fr/esim-turquie.html",
                        "sk": "https://www.esimpont.hu/sk/esim-turecko.html",
                        "ro": "https://www.esimpont.hu/ro/esim-turcia.html",
                        "sr": "https://www.esimpont.hu/sr/esim-turska.html"
                      }
                    }
                  ],
                  "plans": [
                    {
                      "id": "torokorszag-s-1gb-7d",
                      "destinationId": "torokorszag",
                      "name": "Turkey 1 GB / 7 days",
                      "countries": [
                        "TR"
                      ],
                      "dataType": "fixed",
                      "dataGb": 1,
                      "dailyDataGb": null,
                      "validityDays": 7,
                      "throttling": null,
                      "prices": {
                        "HUF": 890,
                        "EUR": 2.9,
                        "RON": 12.9,
                        "RSD": 390
                      },
                      "url": "https://www.esimpont.hu/esim-torokorszag.html?plan=1gb-7d"
                    },
                    {
                      "id": "torokorszag-m-5gb-15d",
                      "destinationId": "torokorszag",
                      "name": "Turkey 5 GB / 15 days",
                      "countries": [
                        "TR"
                      ],
                      "dataType": "fixed",
                      "dataGb": 5,
                      "dailyDataGb": null,
                      "validityDays": 15,
                      "throttling": null,
                      "prices": {
                        "HUF": 1990,
                        "EUR": 5.9,
                        "RON": 28.9,
                        "RSD": 690
                      },
                      "url": "https://www.esimpont.hu/esim-torokorszag.html?plan=5gb-15d"
                    },
                    {
                      "id": "torokorszag-l-20gb-30d",
                      "destinationId": "torokorszag",
                      "name": "Turkey 20 GB / 30 days",
                      "countries": [
                        "TR"
                      ],
                      "dataType": "fixed",
                      "dataGb": 20,
                      "dailyDataGb": null,
                      "validityDays": 30,
                      "throttling": null,
                      "prices": {
                        "HUF": 5590,
                        "EUR": 15.9,
                        "RON": 79.9,
                        "RSD": 1890
                      },
                      "url": "https://www.esimpont.hu/esim-torokorszag.html?plan=20gb-30d"
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "description": "Not modified — the ETag sent in If-None-Match is still current. No body.",
            "headers": {
              "ETag": {
                "description": "Content fingerprint (same as dataVersion). Send it back in If-None-Match.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "private, max-age=3600"
                }
              },
              "Last-Modified": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Missing, invalid or revoked x-api-key, or unknown path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Missing or invalid x-api-key header. Request a key at https://www.esimpont.hu/en/partners.html or partner@esimpont.hu."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: over 5 per second (Retry-After: 1), or the daily quota of 1,000 requests (resets 00:00 UTC).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait (per-second limit only).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Too many requests (limit: 5 per second). Retry after 1 second."
                }
              }
            }
          }
        }
      }
    },
    "/schema": {
      "get": {
        "operationId": "getSchema",
        "summary": "JSON Schema (2020-12) of the plans document",
        "parameters": [
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The last ETag you received; answered with 304 if nothing changed."
          }
        ],
        "responses": {
          "200": {
            "description": "The JSON Schema.",
            "headers": {
              "ETag": {
                "description": "Content fingerprint (same as dataVersion). Send it back in If-None-Match.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "private, max-age=3600"
                }
              },
              "Last-Modified": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "304": {
            "description": "Not modified — the ETag sent in If-None-Match is still current. No body.",
            "headers": {
              "ETag": {
                "description": "Content fingerprint (same as dataVersion). Send it back in If-None-Match.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "private, max-age=3600"
                }
              },
              "Last-Modified": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Missing, invalid or revoked x-api-key, or unknown path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Missing or invalid x-api-key header. Request a key at https://www.esimpont.hu/en/partners.html or partner@esimpont.hu."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: over 5 per second (Retry-After: 1), or the daily quota of 1,000 requests (resets 00:00 UTC).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait (per-second limit only).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Too many requests (limit: 5 per second). Retry after 1 second."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your partner key. Use it server-side only."
      }
    },
    "schemas": {
      "PlansDocument": {
        "title": "Travel eSIM plans feed, version 1",
        "description": "Read-only list of every plan that can be bought online. Prices are final consumer prices including VAT. Generated at build time from the same price list as the website and the checkout.",
        "type": "object",
        "required": [
          "apiVersion",
          "updatedAt",
          "dataVersion",
          "provider",
          "currencies",
          "pricesIncludeVat",
          "esimFee",
          "destinations",
          "plans"
        ],
        "properties": {
          "apiVersion": {
            "const": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the content last changed (not when the file was last built)."
          },
          "dataVersion": {
            "type": "string",
            "description": "Content fingerprint. Unchanged value = nothing to update."
          },
          "schema": {
            "type": "string",
            "description": "Path of this schema on the API (GET /v1/schema)."
          },
          "provider": {
            "type": "object",
            "required": [
              "name",
              "website"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "website": {
                "type": "string",
                "format": "uri"
              },
              "contact": {
                "type": "string"
              }
            }
          },
          "currencies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/currency"
            },
            "minItems": 1
          },
          "pricesIncludeVat": {
            "type": "boolean"
          },
          "esimFee": {
            "type": "object",
            "description": "One-time fee for a new eSIM profile, charged on top of the plan price. Not charged between waived.from and waived.until.",
            "required": [
              "amount",
              "appliesTo"
            ],
            "properties": {
              "amount": {
                "$ref": "#/components/schemas/prices"
              },
              "appliesTo": {
                "type": "string"
              },
              "waived": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "until": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Exclusive end of the fee-free period."
                  }
                }
              }
            }
          },
          "planTerms": {
            "type": "object",
            "description": "Terms that hold for every plan."
          },
          "linkParameters": {
            "type": "object",
            "description": "Query parameters the product pages understand."
          },
          "destinations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/destination"
            }
          },
          "plans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/plan"
            }
          }
        }
      },
      "currency": {
        "type": "string",
        "pattern": "^[A-Z]{3}$"
      },
      "prices": {
        "type": "object",
        "description": "Amount in major units per ISO 4217 currency (HUF has no decimals).",
        "propertyNames": {
          "$ref": "#/components/schemas/currency"
        },
        "additionalProperties": {
          "type": "number",
          "exclusiveMinimum": 0
        }
      },
      "destination": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type",
          "countries",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque, stable identifier."
          },
          "name": {
            "type": "string"
          },
          "type": {
            "enum": [
              "country",
              "region",
              "global"
            ]
          },
          "countries": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "iso2",
                "name",
                "networks"
              ],
              "properties": {
                "iso2": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$"
                },
                "name": {
                  "type": "string"
                },
                "networks": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "localizedUrls": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "plan": {
        "type": "object",
        "required": [
          "id",
          "destinationId",
          "name",
          "countries",
          "dataType",
          "dataGb",
          "dailyDataGb",
          "validityDays",
          "throttling",
          "prices",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable while the plan exists. A changed allowance or validity gives a new id."
          },
          "destinationId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "minItems": 1
          },
          "dataType": {
            "enum": [
              "fixed",
              "daily"
            ],
            "description": "fixed = dataGb for the whole validity; daily = dailyDataGb every day, unused data does not carry over."
          },
          "dataGb": {
            "type": [
              "number",
              "null"
            ],
            "exclusiveMinimum": 0
          },
          "dailyDataGb": {
            "type": [
              "number",
              "null"
            ],
            "exclusiveMinimum": 0
          },
          "validityDays": {
            "type": "integer",
            "minimum": 1
          },
          "throttling": {
            "type": [
              "object",
              "null"
            ],
            "description": "null = full speed until the data is used up.",
            "properties": {
              "afterPercentOfDailyData": {
                "type": "number"
              },
              "speedKbps": {
                "type": "number"
              },
              "dailyDataCarriesOver": {
                "type": "boolean"
              }
            }
          },
          "prices": {
            "$ref": "#/components/schemas/prices"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}