Skip to Content
OpenRoam Docs
Order items

Update an item

Updates a delivered order item, without a charge.

POST
/v1/order-items/{id}/update

Updates a delivered order item, without a charge.

Changes what the item's kind lets a partner change after the purchase, in one call. An update never charges or refunds anything: a change with a price, such as a hotel or flight change, is an amendment (POST /order-items/{id}/amendments/quote). At launch only gift cards can be updated: inputs takes a new recipientEmail and giftMessage, and the gift email is sent again, to the new address with the new message. A card bought without a recipient needs recipientEmail. Every other kind of item returns 422 with code 18004 (UPDATE_NOT_SUPPORTED).

Available when the item's actions.update is available; otherwise the update returns 409 with code 18005 (UPDATE_NOT_AVAILABLE), and details[0].reason repeats actions.update.availability (IN_PROGRESS or NOT_AVAILABLE). The same 409 is returned when the item stops being available during the call, for example after a cancel.

A member of inputs left out or sent as null keeps its current value, and at least one member must be present. An invalid member returns 400 with code 10001 at inputs.<member>, with the same reasons as the order's inputs, and a member the item's kind does not define returns 400 with code 10001 and reason UNSUPPORTED_FIELD. An item of another partner, or an unknown id, returns 404 with code 10004. A malformed body (not valid JSON, inputs missing, null or not an object, or a top-level member other than inputs) returns 400 with code 10001 before the item is read. The checks on the item then run in this order: 404, 422, 409, then 400 for the members of inputs.

Returns the item exactly as GET /order-items/{id} returns it. No webhook is sent for an update.

Requires an Idempotency-Key header (a UUID). Repeating a completed request with the same key and body returns 200 with the item as GET /order-items/{id} returns it now, and changes nothing again (no gift email is sent again). One still running returns 409 with code 12002 (IDEMPOTENCY_KEY_IN_PROGRESS) and a Retry-After header, and a different body with the same key 409 with code 12001. A request that ended in an error can be sent again with the same key and body. Updating the same item again needs a new key.

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

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

The members to change.

  1. body

The change to make to a purchased item. An update never charges or refunds anything.

inputs*

Required. A JSON object with the members to change; the item's kind defines them. At launch only a gift card can be updated, with recipientEmail and giftMessage. A member left out or sent as null keeps its current value, and at least one member must be present. A member that the item's kind does not define is 400 / 10001 with UNSUPPORTED_FIELD at inputs.<member>.

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 POST 'https://api.sandbox.openroam.com/v1/order-items/01a1432e-7121-7b0e-a0a0-c35454d3b883/update' \  -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \  -H 'Content-Type: application/json' \  -d '{  "inputs": {}}'
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"      }    }  }}

Quote an amendment POST

Quotes a change to a delivered order item. Available only when the item's `actions.amendment` is `available`: the item must be fulfilled, not refunded, and its product must support automatic changes. Items whose changes need manual review show `manualReview` and use the manual amendment routes instead. A kind of item that can never be amended returns `422` with code `18002` (`AMENDMENT_NOT_SUPPORTED`); otherwise an amendment that is not allowed now returns `409` with code `18003` (`AMENDMENT_NOT_AVAILABLE`), and `details[0].reason` repeats `actions.amendment.availability` (`MANUAL_REVIEW` or `NOT_AVAILABLE`). An item of another partner, or an unknown id, returns `404` with code `10004`. Send the requested change in `attributes`, in the shape the item's product defines; top-level names that start with `_` are reserved for OpenRoam and ignored. The response has an `amendmentRequestId`, the time the quote was made (`processedAt`), the time it expires (`expiresAt`) and one or more `options`, each with an `id`, an `amountToPay` and an `amountToRefund` in the API key's currency, and an `amendmentFee`: a fee for the change, already included in those amounts, or `null` when none applies. Nothing changes and nothing is charged until you confirm the quote with `POST /order-items/{id}/amendments/confirm`, before `expiresAt`. Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key returns `409` with code `12000` (`IDEMPOTENCY_KEY_ALREADY_USED`): a quote is not kept, so request a new one with a new key. One still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a `Retry-After` header, and a different body with the same key `409` with code `12001`. A request that ended in an error can be sent again with the same key and body.

Create a wallet POST

Creates an empty wallet in a currency the partner has no wallet in yet. Take `currencyId` from `GET currencies`. The new wallet starts with a zero balance. Without a `label` it is named after its currency, for example `USD wallet`. The partner's first wallet is always selected; for a later one, `isSelected: true` makes it the selected wallet in place of the current one. Returns `201` without a body; list the wallets to read it. A second wallet in the same currency returns `400` with code `17000` (`WALLET_CURRENCY_ALREADY_EXISTS`); a label already used by another of the partner's wallets, ignoring case, returns `400` with code `17001` (`WALLET_LABEL_ALREADY_EXISTS`).