Skip to Content
OpenRoam Docs
Order items

Get an order item

Gets an order item: what was bought, its delivery, its refund and what you can do next.

GET
/v1/order-items/{id}

Gets an order item: what was bought, its delivery, its refund and what you can do next.

Requires the read order permission. Returns the item exactly as it appears in items[] of the order response, including orderId, the order it belongs to. fulfillment.status and refund.status give its state; actions.cancellation says whether it can be cancelled now, actions.amendment whether it can be amended and actions.update whether it can be updated. An item of another partner, or an unknown id, returns 404 with code 10004; a malformed id or an unknown query parameter returns 400 with code 10001.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

Order item id (items[].id from the order response).

Formatuuid

Response Body

OK

  1. response

One purchased unit of an order.

id*string

Order item id, used by the order-item endpoints. It is not the offer's publicId.

Formatuuid
orderId*string

The order the item belongs to.

Formatuuid
productType*"esim"
Value in"esim"
price*

The price paid for the item at purchase, in the order's currency.

purchasedProduct*

The eSIM plan an order item bought. name is the package name, as the offer names it, and logoUrl is the destination image. An eSIM has no monetary value, so there is no value. inputs echoes the item's inputs with device and eSIM identifiers masked.

fulfillment*
actions*

Whether the item can be amended or cancelled now.

createdAt*string

When the item was created (UTC).

Formatdate-time
effectivePaidAmount*

What you have paid for the item, net of every amount returned: price plus completed amendment charges, less completed amendment credits and less the completed refund.

refund?|

The recorded refund, or null when no refund has been started.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/order-items/01a1432e-7121-7b0e-a0a0-c35454d3b883'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",  "productType": "esim",  "price": {    "amount": 0,    "currency": "string"  },  "purchasedProduct": {    "name": "string",    "countryCode": "string",    "logoUrl": "string",    "inputs": {      "eid": "string",      "imei2": "string",      "iccid": "string",      "travelStartDate": "2019-08-24",      "isInstant": true    },    "details": {      "orderType": "esim",      "isInstant": true,      "destination": {        "id": "string",        "name": "string",        "code": "string"      }    }  },  "fulfillment": {    "status": "pending",    "result": {      "details": {        "iccid": "string",        "mode": "deferred",        "provisioning": {          "status": "notStarted"        },        "canProvision": true,        "esimStatus": "new",        "profileStatus": "empty",        "installation": {          "lpaCode": "string",          "smdpAddress": "string",          "activationCode": "string",          "qrCodeUrl": "string",          "iosQuickInstall": "string",          "androidQuickInstall": "string"        },        "pin": "string",        "puk": "string",        "phoneNumber": "string",        "data": {          "amount": 0,          "unit": "string",          "isUnlimited": true,          "label": "string"        },        "voice": {          "amount": 0,          "unit": "string",          "isUnlimited": true,          "label": "string",          "type": "string"        },        "sms": {          "amount": 0,          "unit": "string",          "isUnlimited": true,          "label": "string",          "type": "string"        },        "apn": {          "apn": "string",          "apnUsername": "string",          "apnPassword": "string"        },        "addons": [          {            "packageName": "string",            "usage": {              "start": "2019-08-24T14:15:22Z",              "end": "2019-08-24T14:15:22Z",              "allowedData": 0,              "remainingData": 0,              "isDataUnlimited": true,              "allowedSms": 0,              "remainingSms": 0,              "isSmsUnlimited": true,              "allowedVoice": 0,              "remainingVoice": 0,              "isVoiceUnlimited": true            }          }        ],        "notes": [          "string"        ],        "fulfilledAt": "2019-08-24T14:15:22Z"      }    },    "failure": {      "code": 0,      "name": "string",      "message": "string"    },    "progress": {      "code": "string",      "message": "string"    }  },  "actions": {    "amendment": {      "availability": "available",      "reason": "string"    },    "cancellation": {      "availability": "available",      "reason": "string"    },    "update": {      "availability": "available",      "reason": "string"    }  },  "createdAt": "2019-08-24T14:15:22Z",  "effectivePaidAmount": {    "amount": 0,    "currency": "string"  },  "refund": {    "status": "pending",    "amount": {      "amount": 0,      "currency": "string"    },    "updatedAt": "2019-08-24T14:15:22Z",    "wallet": {      "label": "string",      "credited": {        "amount": 0,        "currency": "string"      }    }  }}

List item amendments GET

Lists every amendment of an order item. Returns the whole list as an array, without paging. Each amendment has `id`, `orderItemId`, `status`, `productType`, `createdAt`, `amountToPay` and `amountToRefund`. An item of another partner, or an unknown id, returns `404` with code `10004`.

Preview an item cancellation GET

Previews the cancellation penalty and expected refund for an order item. Requires the `read` order permission. Returns `penaltyAmount`, the `cancellationFee` kept in addition to it (`null` when none applies) and the expected `refundAmount`, all in the order currency, `isRefundable`, the cancellation band in effect, priced at the penalty (`appliedPenalties`: at most one `{ from, penaltyAmount }`), `effectiveCancellationDate` and `checkInDate`, calculated with the same rules as the partner portal. The fee comes out of what the penalty leaves, so the refund is never negative. `isRefundable: false` means the penalty alone keeps the whole price, so the item cannot be cancelled; it is not an error. A fee that takes what the penalty leaves does not make it false: the item can still be cancelled, with a refund of 0. The preview does not cancel the item or change its state, and it does not lock the penalty: the cancel call recalculates it, so a later cancellation band may apply. The preview refuses what the cancel refuses. A delivered item of a kind that cannot take back a delivery (airtime, utility, gift cards, eSIMs) can never be cancelled and returns `422` with code `18000` (`CANCELLATION_NOT_SUPPORTED`). Otherwise, when the item's `actions.cancellation` is not `available`, it returns `409` with code `18001` (`CANCELLATION_NOT_AVAILABLE`), and `details[0].reason` repeats `actions.cancellation.availability`. A refund started by OpenRoam support returns the same `409` with `MANUAL_REVIEW`. A delivered item is priced with its product's cancellation rules. An item that was not delivered has no cancellation to price: a rejected item whose automatic refund has not started previews a full refund of what was paid (after a failed refund, the amounts that refund is retried with), with a `penaltyAmount` of 0 and no `cancellationFee` or `appliedPenalties`. A cancellation the product refuses, for example after check-out, returns `400` with code `10001`. An item of another partner, or an unknown id, returns `404` with code `10004`.