Retrieve an Order

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/zim/doc/esim-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "eSIM API MCP server": {
    "url": "https://bump.sh/zim/doc/esim-api/mcp"
  }
}

Close
GET /orders/{orderID}

Returns an Order created by the authenticated User. With expand=true the Order also includes its plan, subscription (with its eSIM), notifyRecipient and failureReason.

Path parameters

  • orderID string Required

    ID of the Order

Query parameters

  • expand boolean

    Default value is false.

Responses

  • 200 application/json

    Order fetched successfully

    Hide response attributes Show response attributes object
    • id string

      The Order's ID

    • status string

      Statuses:

      • PENDING_APPROVAL - The Order is awaiting approval from an Admin / Purchaser / Owner
      • PENDING_PAYMENT - The Order is awaiting payment
      • PROCESSING - The Order is being processed by the network and should soon be fulfilled
      • FULFILLED - The Order has been fulfilled and the associated Subscription / eSIM is ready
      • CANCELLED - The Order has been cancelled before being charged
      • REFUNDED - The Order has been cancelled and its charge reversed
      • FAILED - The Order has failed — see failureReason for details
      • REPLACED - The Order has been superseded by a newer one
      • IN_BASKET - The Order is currently sitting in the User's basket

      Values are PENDING_APPROVAL, PENDING_PAYMENT, PROCESSING, FULFILLED, CANCELLED, REFUNDED, FAILED, REPLACED, or IN_BASKET.

    • accountID string

      The Account ID linked to the Order

    • planID string

      The Plan ID linked to the Order

    • userID string

      The User ID for which the Order was generated

    • type string

      Types:

      • ONE_OFF - The Order is a one-off purchase
      • TOP_UP - The Order tops up an existing Subscription
      • RECURRING - The Order is part of a recurring Subscription (UK domestic plans)

      Values are ONE_OFF, TOP_UP, or RECURRING.

    • notifyRecipient boolean

      If true, the end User has been (or will be) notified about this Order. Returned with expand=true.

    • failureReason string

      Free-text explanation set when status is FAILED. Returned with expand=true.

    • plan object
      Hide plan attributes Show plan attributes object
      • id string
      • name string
      • scope string
        • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

        Values are LOCAL, REGIONAL, or GLOBAL.

      • category string

        Values are REGULAR, UNLIMITED, or MIXED.

      • type string
        • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

        Values are DATA or VOICE_AND_DATA.

      • isRecurring boolean

        true for recurring plans such as UK domestic plans

      • recurringInterval string | null

        Billing interval of recurring plans (MONTHLY for UK domestic plans), null for one-off plans

        Values are DAILY, WEEKLY, MONTHLY, YEARLY, or null.

      • destination object
        Hide destination attributes Show destination attributes object
        • name string
        • isoAlpha3 string
        • regions array[object]
          Hide regions attributes Show regions attributes object
          • name string
          • abbreviation string
        • scopes object

          Returned by GET /destinations/{iso3} only

          Hide scopes attributes Show scopes attributes object
          • local boolean
          • regional boolean
          • global boolean
      • region object
        Hide region attributes Show region attributes object
        • name string
        • abbreviation string
      • dataUnit string

        Possible values:

        • MB - MegaByte representation
        • GB - GigaByte representation

        Values are MB or GB.

      • dataValue number

        Details:

        • If dataValue >= 0 then the plan is capped to that amount of consumable data
        • If dataValue == -1 then the plan is unlimited and does not have a cap on consumable data
      • callUnit string

        Details:

        • MINUTES - Minutes representation
        • HOURS - Hours representation

        Values are MINUTES or HOURS.

      • callValue number

        Details:

        • If callValue >= 0 then the plan is capped to that amount of consumable call time
        • If callValue == -1 then the plan is unlimited and does not have a cap on call time
      • smsUnit string
      • smsValue number

        Details:

        • If smsValue >= 0 then the plan is capped to that amount of consumable SMS sent
        • If smsValue == -1 then the plan is unlimited and does not have a cap on SMS sent
      • durationUnit string
      • durationValue number
      • features array[object]
        Hide features attributes Show features attributes object
        • name string

          Possible values:

          • HOTSPOT - The plan does support the hotspot function
          • TOP_UP - The plan does support top up operations
          • 3G - The plan and its associated network supports speeds up to 3G
          • 4G - The plan and its associated network supports speeds up to 4G
          • 5G - The plan and its associated network supports speeds up to 5G

          Values are HOTSPOT, TOP_UP, 3G, 4G, or 5G.

        • category string

          Values are UTILITY, BILLING, or NETWORK.

      • prices array[object]
        Hide prices attributes Show prices attributes object
        • currencyISO string
        • value number

          The unit amount in minor units (e.g. cents, if supported), represented as a signed integer

        • minorUnitsExponent number

          Indicates the number of decimals in the price for currencies supporting this format or 0 for zero-decimal currencies such as JPY. Examples:

          • A USD price value of 490 with a minorUnitsExponent of 2 would be $4.90
          • A JPY price value of 775 with a minorUnitsExponent of 0 would be ¥775
        • discountedFrom number

          Present when a valid discountCode was applied — the price before discount, in minor units

      • createdAt string(date-time)
    • subscription object

      Returned with expand=true once the Order is fulfilled

      Hide subscription attributes Show subscription attributes object
      • id string

        The Subscription's ID

      • status string

        Statuses:

        • PROCESSING - The Subscription is being processed and should be ready soon
        • PENDING - The Subscription is ready and is pending first use by the User
        • ACTIVE - The Subscription is currently active and used by the User
        • EXPIRED - The Subscription has expired and is no longer valid
        • CANCEL_PENDING - A cancellation was requested and is awaiting confirmation from the network
        • CANCELLED - The Subscription has been cancelled
        • DEPLETED - The allocation of the Subscription has been fully consumed by the User

        Values are PROCESSING, PENDING, ACTIVE, EXPIRED, CANCEL_PENDING, CANCELLED, or DEPLETED.

      • esimID string

        The associated eSIM ID

      • planID string
      • orderID string
      • userID string
      • accountID string
      • expirationDate string(date-time) | null
      • createdAt string(date-time)
      • plan object

        The associated Plan object (without prices)

        Hide plan attributes Show plan attributes object
        • id string
        • name string
        • scope string
          • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

          Values are LOCAL, REGIONAL, or GLOBAL.

        • category string

          Values are REGULAR, UNLIMITED, or MIXED.

        • type string
          • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

          Values are DATA or VOICE_AND_DATA.

        • isRecurring boolean

          true for recurring plans such as UK domestic plans

        • recurringInterval string | null

          Billing interval of recurring plans (MONTHLY for UK domestic plans), null for one-off plans

          Values are DAILY, WEEKLY, MONTHLY, YEARLY, or null.

        • destination object
          Hide destination attributes Show destination attributes object
          • name string
          • isoAlpha3 string
          • regions array[object]
            Hide regions attributes Show regions attributes object
            • name string
            • abbreviation string
          • scopes object

            Returned by GET /destinations/{iso3} only

            Hide scopes attributes Show scopes attributes object
            • local boolean
            • regional boolean
            • global boolean
        • region object
          Hide region attributes Show region attributes object
          • name string
          • abbreviation string
        • dataUnit string

          Possible values:

          • MB - MegaByte representation
          • GB - GigaByte representation

          Values are MB or GB.

        • dataValue number

          Details:

          • If dataValue >= 0 then the plan is capped to that amount of consumable data
          • If dataValue == -1 then the plan is unlimited and does not have a cap on consumable data
        • callUnit string

          Details:

          • MINUTES - Minutes representation
          • HOURS - Hours representation

          Values are MINUTES or HOURS.

        • callValue number

          Details:

          • If callValue >= 0 then the plan is capped to that amount of consumable call time
          • If callValue == -1 then the plan is unlimited and does not have a cap on call time
        • smsUnit string
        • smsValue number

          Details:

          • If smsValue >= 0 then the plan is capped to that amount of consumable SMS sent
          • If smsValue == -1 then the plan is unlimited and does not have a cap on SMS sent
        • durationUnit string
        • durationValue number
        • features array[object]
          Hide features attributes Show features attributes object
          • name string

            Possible values:

            • HOTSPOT - The plan does support the hotspot function
            • TOP_UP - The plan does support top up operations
            • 3G - The plan and its associated network supports speeds up to 3G
            • 4G - The plan and its associated network supports speeds up to 4G
            • 5G - The plan and its associated network supports speeds up to 5G

            Values are HOTSPOT, TOP_UP, 3G, 4G, or 5G.

          • category string

            Values are UTILITY, BILLING, or NETWORK.

        • prices array[object]
          Hide prices attributes Show prices attributes object
          • currencyISO string
          • value number

            The unit amount in minor units (e.g. cents, if supported), represented as a signed integer

          • minorUnitsExponent number

            Indicates the number of decimals in the price for currencies supporting this format or 0 for zero-decimal currencies such as JPY. Examples:

            • A USD price value of 490 with a minorUnitsExponent of 2 would be $4.90
            • A JPY price value of 775 with a minorUnitsExponent of 0 would be ¥775
          • discountedFrom number

            Present when a valid discountCode was applied — the price before discount, in minor units

        • createdAt string(date-time)
      • activity object | null
        Hide activity attributes Show activity attributes object | null
        • currentBalanceBytes number

          The current balance in bytes for the Subscription

        • spentBalanceBytes number

          The spent balance in bytes for the Subscription

        • initialBalanceBytes number

          The initial balance in bytes for the Subscription

        • lastUpdatedAt string(date-time)

          The report's last update

      • cancelAtPeriodEnd boolean

        true when the Subscription is scheduled to be cancelled at cancelEffectiveDate

      • cancelEffectiveDate string(date-time)

        Date a scheduled cancellation takes effect

    • createdAt string(date-time)
  • 401 application/json

    Missing or invalid access token or X-App-Identifier

    Hide response attributes Show response attributes object
  • 404 application/json

    Resource not found or not owned by your Account

    Hide response attributes Show response attributes object
GET /orders/{orderID}
curl \
 --request GET 'https://zim.api.zimconnections.com/orders/ordr_GMAVA4ISiqfWSG0ArGOzB' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "X-App-Identifier: $API_KEY"
Response examples (200)
{
  "id": "ordr_GMAVA4ISiqfWSG0ArGOzB",
  "status": "PENDING_APPROVAL",
  "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
  "planID": "plan_guaGulGcrqgTYboPvetgu",
  "userID": "user_yf95A86RIkVxau2gzBsjV",
  "type": "ONE_OFF",
  "notifyRecipient": true,
  "failureReason": "string",
  "plan": {
    "id": "plan_guaGulGcrqgTYboPvetgu",
    "name": "France - 10GB - 14 days",
    "scope": "LOCAL",
    "category": "REGULAR",
    "type": "DATA",
    "isRecurring": false,
    "recurringInterval": "DAILY",
    "destination": {
      "name": "United Kingdom",
      "isoAlpha3": "GBR",
      "regions": [
        {
          "name": "Europe",
          "abbreviation": "EU"
        }
      ],
      "scopes": {
        "local": true,
        "regional": true,
        "global": true
      }
    },
    "region": {
      "name": "Europe",
      "abbreviation": "EU"
    },
    "dataUnit": "GB",
    "dataValue": 10,
    "callUnit": "MINUTES",
    "callValue": 100,
    "smsUnit": "SMS",
    "smsValue": 100,
    "durationUnit": "DAYS",
    "durationValue": 14,
    "features": [
      {
        "name": "HOTSPOT",
        "category": "UTILITY"
      }
    ],
    "prices": [
      {
        "currencyISO": "usd",
        "value": 490,
        "minorUnitsExponent": 2,
        "discountedFrom": 590
      }
    ],
    "createdAt": "2026-05-04T09:42:00Z"
  },
  "subscription": {
    "id": "subs_BiPtvfzYKwcyNMNvTGmLO",
    "status": "PROCESSING",
    "esimID": "esim_kNsYsgLWJCesLTLsjoRGp",
    "planID": "plan_guaGulGcrqgTYboPvetgu",
    "orderID": "ordr_GMAVA4ISiqfWSG0ArGOzB",
    "userID": "user_yf95A86RIkVxau2gzBsjV",
    "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
    "expirationDate": "2026-05-04T09:42:00Z",
    "createdAt": "2026-05-04T09:42:00Z",
    "plan": {
      "id": "plan_guaGulGcrqgTYboPvetgu",
      "name": "France - 10GB - 14 days",
      "scope": "LOCAL",
      "category": "REGULAR",
      "type": "DATA",
      "isRecurring": false,
      "recurringInterval": "DAILY",
      "destination": {
        "name": "United Kingdom",
        "isoAlpha3": "GBR",
        "regions": [
          {
            "name": "Europe",
            "abbreviation": "EU"
          }
        ],
        "scopes": {
          "local": true,
          "regional": true,
          "global": true
        }
      },
      "region": {
        "name": "Europe",
        "abbreviation": "EU"
      },
      "dataUnit": "GB",
      "dataValue": 10,
      "callUnit": "MINUTES",
      "callValue": 100,
      "smsUnit": "SMS",
      "smsValue": 100,
      "durationUnit": "DAYS",
      "durationValue": 14,
      "features": [
        {
          "name": "HOTSPOT",
          "category": "UTILITY"
        }
      ],
      "prices": [
        {
          "currencyISO": "usd",
          "value": 490,
          "minorUnitsExponent": 2,
          "discountedFrom": 590
        }
      ],
      "createdAt": "2026-05-04T09:42:00Z"
    },
    "activity": {
      "currentBalanceBytes": 42.0,
      "spentBalanceBytes": 42.0,
      "initialBalanceBytes": 42.0,
      "lastUpdatedAt": "2026-05-04T09:42:00Z"
    },
    "cancelAtPeriodEnd": false,
    "cancelEffectiveDate": "2026-05-04T09:42:00Z"
  },
  "createdAt": "2026-05-12T14:39:23.149Z"
}
Response examples (401)
{
  "statusCode": 401,
  "message": "Unauthorized"
}
Response examples (404)
{
  "statusCode": 404,
  "message": "Record not found",
  "error": "Not Found"
}