# eSIM Park plans API — OpenAPI 3.1. Generated by scripts/gen-developers-page.py; do not edit.
openapi: "3.1.0"
info:
  title: "eSIM Park plans API"
  version: "1.0.0"
  summary: "Every eSIM Park plan that can be bought online, with final prices in six currencies."
  description: "Read-only. One API key per partner in the x-api-key header; request one at partner@esimpark.com. Limits per key: 5 requests/second (burst 10), 1000 requests/day. Documentation: https://www.esimpark.com/partners.html"
  termsOfService: "https://www.esimpark.com/partners.html#terms"
  contact:
    name: "eSIM Park partners"
    email: "partner@esimpark.com"
    url: "https://www.esimpark.com/partners.html"
servers:
  - url: "https://uj684erdvk.execute-api.eu-central-1.amazonaws.com/v1"
security:
  - ApiKey: []
paths:
  "/plans":
    get:
      operationId: "getPlans"
      summary: "All destinations and plans"
      parameters:
        - name: "If-None-Match"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "The ETag of your last copy; a match returns 304."
      responses:
        "200":
          description: "The plans document."
          headers:
            ETag:
              description: "Content fingerprint (dataVersion). Send it back in If-None-Match."
              schema:
                type: "string"
            Last-Modified:
              description: "When the content last changed."
              schema:
                type: "string"
            Cache-Control:
              description: "private, max-age=3600"
              schema:
                type: "string"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PlansDocument"
        "304":
          description: "Not modified: the If-None-Match ETag is current. No body."
        "403":
          description: "Missing, wrong or disabled x-api-key (\"Missing or invalid x-api-key header. Request a key at partner@esimpark.com.\"), or unknown path (\"Forbidden. Endpoints: GET /v1/plans, GET /v1/schema with an x-api-key header.\")."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "Rate limit (5/s, burst 10; Retry-After: 1) or daily quota (1000/day, resets 00:00 UTC)."
          headers:
            Retry-After:
              description: "Seconds to wait (sent on the per-second limit)."
              schema:
                type: "integer"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
  "/schema":
    get:
      operationId: "getSchema"
      summary: "JSON Schema (2020-12) of the /plans response"
      parameters:
        - name: "If-None-Match"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "The ETag of your last copy; a match returns 304."
      responses:
        "200":
          description: "The JSON Schema."
          headers:
            ETag:
              description: "Content fingerprint (dataVersion). Send it back in If-None-Match."
              schema:
                type: "string"
            Last-Modified:
              description: "When the content last changed."
              schema:
                type: "string"
            Cache-Control:
              description: "private, max-age=3600"
              schema:
                type: "string"
          content:
            "application/json":
              schema:
                type: "object"
        "304":
          description: "Not modified: the If-None-Match ETag is current. No body."
        "403":
          description: "Missing, wrong or disabled x-api-key (\"Missing or invalid x-api-key header. Request a key at partner@esimpark.com.\"), or unknown path (\"Forbidden. Endpoints: GET /v1/plans, GET /v1/schema with an x-api-key header.\")."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "Rate limit (5/s, burst 10; Retry-After: 1) or daily quota (1000/day, resets 00:00 UTC)."
          headers:
            Retry-After:
              description: "Seconds to wait (sent on the per-second limit)."
              schema:
                type: "integer"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    ApiKey:
      type: "apiKey"
      in: "header"
      name: "x-api-key"
  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"