Create 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
POST /v2/orders

Unified order creation for one-off and top-up travel plans. The Order is paid the way your Account's billing is set up:

  • Advance Pay - debited from your Account's prepaid wallet. A wallet that does not cover price × recipients is refused with INSUFFICIENT_BALANCE and nothing is created; there is no card fallback. Defaults to the caller as recipient.
  • Post-paid - billed on your monthly post-paid invoice. recipientUserNanoIDs is required.
  • An Account billed by card only cannot order through the API and is refused with PAYMENT_METHOD_NOT_ALLOWED: ask your account manager to enable Advance Pay.

One Order is created per recipient; the response describes the first one. Fulfilment is asynchronous: poll GET /orders/{orderID} until the status is FULFILLED (or FAILED).

To top up an existing Subscription set type: TOP_UP, topUpSubscriptionNanoID, and a planID taken from GET /subscriptions/{subscriptionID}/compatible-plans.

Not idempotent — see the Errors topic before retrying.

application/json

Body Required

  • type string Required

    Values are ONE_OFF or TOP_UP.

  • planID string Required
  • accountID string Required

    Your Account ID. Orders are always created for the caller's Account.

  • currencyISO string

    Ignored: Orders are charged in your Account's billing currency, which payment.currencyISO reports.

  • recipientUserNanoIDs array[string]

    Users of your Account receiving the plan — one Order per recipient, charged price × recipients. Optional for Advance Pay Accounts (defaults to the caller), required for post-paid Accounts. For TOP_UP, every recipient must own the Subscription.

    Not more than 50 elements. Maximum length of each is 32.

  • topUpSubscriptionNanoID string

    Required when type is TOP_UP — the Subscription to top up

  • notifyRecipient boolean

    If true, a notification (push / SMS or email) is sent to the end User based on the Account preferences

    Default value is true.

  • activationDate string

    Advance Pay Accounts only. Activation date (ISO 8601 or DD-MM-YYYY), not in the past.

Responses

  • 201 application/json

    Order created

    Hide response attributes Show response attributes object
    • order object

      The first Order created

      Hide order attributes Show order 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)
    • payment object
      Hide payment attributes Show payment attributes object
      • paymentNanoID string
      • status string

        Values are PENDING, RECEIVED, RETURNED, FAILED, or REFUNDED.

      • amount number

        Total amount for all recipients, in minor units

      • currencyISO string
    • nextAction object
      Hide nextAction attributes Show nextAction attributes object
      • type string
        • none - nothing to do, the Order is being processed * stripe_invoice - pay the invoice at url

        Values are none or stripe_invoice.

      • url string(uri)

        Hosted invoice URL when type is stripe_invoice

  • 400 application/json

    Invalid request or refused by a business rule

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

    Missing or invalid access token or X-App-Identifier

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

    Your role is not allowed to perform this operation

    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
POST /v2/orders
curl \
 --request POST 'https://zim.api.zimconnections.com/v2/orders' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "X-App-Identifier: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "type": "ONE_OFF",
  "planID": "plan_guaGulGcrqgTYboPvetgu",
  "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
  "currencyISO": "usd",
  "recipientUserNanoIDs": [
    "user_yf95A86RIkVxau2gzBsjV",
    "user_ozxEbkTyvLPhhoglcALXR"
  ]
}'
Request examples
{
  "type": "ONE_OFF",
  "planID": "plan_guaGulGcrqgTYboPvetgu",
  "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
  "currencyISO": "usd",
  "recipientUserNanoIDs": [
    "user_yf95A86RIkVxau2gzBsjV",
    "user_ozxEbkTyvLPhhoglcALXR"
  ]
}
{
  "type": "TOP_UP",
  "planID": "plan_guaGulGcrqgTYboPveAAB",
  "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
  "topUpSubscriptionNanoID": "subs_BiPtvfzYKwcyNMNvTGmLO",
  "recipientUserNanoIDs": [
    "user_yf95A86RIkVxau2gzBsjV"
  ]
}
Response examples (201)
{
  "order": {
    "id": "ordr_GMAVA4ISiqfWSG0ArGOzB",
    "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
    "planID": "plan_guaGulGcrqgTYboPvetgu",
    "userID": "user_yf95A86RIkVxau2gzBsjV",
    "createdAt": "2026-10-27T14:39:23.149Z",
    "status": "PROCESSING",
    "type": "ONE_OFF"
  },
  "payment": {
    "paymentNanoID": "paym_4FzTYboPvetguABCDEFG",
    "status": "RECEIVED",
    "amount": 2980,
    "currencyISO": "usd"
  },
  "nextAction": {
    "type": "none"
  }
}
Response examples (400)
{
  "statusCode": 400,
  "message": [
    "property foo should not exist"
  ],
  "error": "Bad Request"
}
Response examples (401)
{
  "statusCode": 401,
  "message": "Unauthorized"
}
Response examples (403)
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}
Response examples (404)
{
  "statusCode": 404,
  "message": "Record not found",
  "error": "Not Found"
}