Update an item
Updates a delivered order item, without a charge.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringOrder item id (items[].id from the order response).
uuidIdempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuidThe members to change.
- 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>.
OK
- response
One purchased unit of an order.
id*stringOrder item id, used by the order-item endpoints. It is not the offer's publicId.
uuidorderId*stringThe order the item belongs to.
uuidproductType*"esim""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*stringWhen the item was created (UTC).
date-timeeffectivePaidAmount*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.
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": {}}'{ "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`).