Inbox eSIM

Lists Inbox eSIM data plans for a destination (country, city, region such as Europe, or 'global'), cheapest first, with plan_id, data in GB, validity in days and price in USD. Data only, no phone number; works on unlocked eSIM phones.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Where the customer travels, e.g. 'Japan', 'USA', 'Europe', 'Bangkok'."
    },
    "min_data_gb": {
      "type": "number",
      "description": "Optional: only plans with at least this much data."
    },
    "min_days": {
      "type": "integer",
      "description": "Optional: only plans valid for at least this many days (the trip length)."
    }
  },
  "required": [
    "destination"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "plans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "plan_id": {
            "type": "string"
          },
          "place": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "country",
              "regional",
              "global"
            ]
          },
          "data_gb": {
            "type": "number"
          },
          "valid_days": {
            "type": "integer"
          },
          "price_usd": {
            "type": "string",
            "description": "Final price in USD, e.g. \"5.90\"."
          },
          "countries": {
            "type": "integer",
            "description": "Regional and global plans: how many countries they cover."
          },
          "details": {
            "type": "string"
          },
          "page_url": {
            "type": "string"
          }
        },
        "required": [
          "plan_id",
          "place",
          "kind",
          "data_gb",
          "valid_days",
          "price_usd",
          "details",
          "page_url"
        ]
      }
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "plans"
  ]
}

Starts the purchase of one eSIM plan for the customer and returns a payment link. Pay it with the Machine Payments Protocol (HTTP 402, Stripe shared payment token) to complete the order. Before calling, confirm the plan, the price and the email with the customer, and get their agreement to the terms: By buying, the customer asks for the eSIM to be sent at once and accepts the terms (https://inboxesim.com/terms): the 14-day right to withdraw ends once the eSIM is installed. An eSIM that was never installed or used can be refunded within 30 days from its order page, less the payment fee (in full within 14 days in the EU and UK).

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "A plan_id from find_esim_plans, e.g. 'japan-5gb-30d'."
    },
    "customer_email": {
      "type": "string",
      "description": "Where the QR code and install link are sent."
    },
    "customer_agreed_to_terms": {
      "type": "boolean",
      "description": "true only if the customer accepted the terms quoted in this tool's description."
    }
  },
  "required": [
    "plan_id",
    "customer_email",
    "customer_agreed_to_terms"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "payment_required",
        "buy_on_page"
      ]
    },
    "plan": {
      "type": "object",
      "properties": {
        "plan_id": {
          "type": "string"
        },
        "place": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "country",
            "regional",
            "global"
          ]
        },
        "data_gb": {
          "type": "number"
        },
        "valid_days": {
          "type": "integer"
        },
        "price_usd": {
          "type": "string",
          "description": "Final price in USD, e.g. \"5.90\"."
        },
        "countries": {
          "type": "integer",
          "description": "Regional and global plans: how many countries they cover."
        },
        "details": {
          "type": "string"
        },
        "page_url": {
          "type": "string"
        }
      },
      "required": [
        "plan_id",
        "place",
        "kind",
        "data_gb",
        "valid_days",
        "price_usd",
        "details",
        "page_url"
      ]
    },
    "amount_usd": {
      "type": "string"
    },
    "payment_link": {
      "type": "string",
      "description": "POST here and answer the HTTP 402 challenge."
    },
    "how_to_pay": {
      "type": "string"
    },
    "browser_fallback": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "page_url": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "plan"
  ]
}

Says whether a phone model is likely to take an eSIM (likely, unlikely or check), from the model name, with how to be sure on the phone itself. Call it before buy_esim when the customer is unsure.

{
  "type": "object",
  "properties": {
    "device": {
      "type": "string",
      "description": "The phone or tablet model, e.g. 'iPhone 13', 'Galaxy S23', 'Pixel 7a'."
    }
  },
  "required": [
    "device"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "device": {
      "type": "string"
    },
    "verdict": {
      "type": "string",
      "enum": [
        "likely",
        "unlikely",
        "check"
      ]
    },
    "reason": {
      "type": "string"
    },
    "how_to_check": {
      "type": "string"
    }
  },
  "required": [
    "device",
    "verdict",
    "reason",
    "how_to_check"
  ]
}

Where an Inbox eSIM order is (awaiting_payment, preparing, ready_to_install, installed, in_use, ended, refunded, cancelled, with_support), with data used, the end date and the order page. Needs the order number and the email it was bought with.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order number, e.g. 'ISJPAH2PXG2C' (in the paid response and the email)."
    },
    "customer_email": {
      "type": "string",
      "description": "The email the order was bought with."
    }
  },
  "required": [
    "order_id",
    "customer_email"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_payment",
        "preparing",
        "ready_to_install",
        "installed",
        "in_use",
        "ended",
        "refunded",
        "cancelled",
        "with_support"
      ]
    },
    "place": {
      "type": "string"
    },
    "plan": {
      "type": "string"
    },
    "top_up_of": {
      "type": "string"
    },
    "data_used_gb": {
      "type": "number"
    },
    "data_total_gb": {
      "type": "number"
    },
    "valid_until": {
      "type": "string"
    },
    "order_url": {
      "type": "string"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "status",
    "place",
    "plan",
    "order_url"
  ]
}