Skip to main content

Issuing eSIM Replacement

This guide will show how to issue an eSIM replacement for providers that have a product of type esim_replacement.

1. Find the eSIM Replacement product id​

Use the Get Products API to search for an esim_replacement type product for the requested provider.

Example​

curl -L -X GET 'https://api.mobimatter.com/mobimatter/api/v2/products?provider=3&category=esim_replacement' \
-H 'Accept: text/plain' \
-H 'merchantId: <MerchantId>' \
-H 'api-key: <API_KEY_VALUE>'

2. Place a New Order​

Using the product id from the previous step, create a new order. Make sure to pass the old order id as the addOnOrderIdentifier

curl -L -X POST 'https://api.mobimatter.com/mobimatter/api/v2/order' \
-H 'Content-Type: application/json' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>' \
--data-raw '{
  "productId": "9f0d2dcb-31d7-46d0-846d-bb68aa710e7e",
  "productCategory": "esim_replacement",
  "addOnOrderIdentifier": "XYZ-2322234",
  "callbackUrl": "https://your-server.com/webhook/order-completed"
}'

You can optionally pass a callbackUrl (must be HTTPS) to receive a webhook notification when the order completes, instead of polling for order status. See Order Completion Webhooks for full details.

3. Complete the Order​

Complete the order with the Complete Order API.

Completion behaviour varies by provider. For most providers the replacement completes synchronously and the response returns the order already in the Completed state. 3HK is the exception: it completes in the background and returns the order in the Processing state.

Handle both outcomes from the same call. Do not assume the order is still processing, and do not assume it is already done.

4. Get order completion status​

The completion webhook fires as soon as the order completes — immediately for the synchronous providers, later for 3HK. Because it behaves the same way regardless of provider, it is the one path that does not require provider-specific branching.

  • Webhook (recommended): Pass a callbackUrl in step 2 and treat the webhook as your source of truth for completion, with the Complete Order response as an early signal. See Order Completion Webhooks for payload format and signature verification.

    Your handler must be idempotent. For synchronous providers the callback can arrive while the Complete Order call is still returning, so fulfilling on both paths would process the same completion twice. Use eventData.orderId as the idempotency key.

  • Polling: Poll Get Order as a fallback, once the webhook retry window has been exhausted or if you cannot expose a public endpoint.

Once the order is Completed you can access the new LPA string and QR code.

The original eSIM remains queryable after the replacement — Get Order and the usage endpoints continue to work against the original order id. Keep the original order in your records and link the replacement to it rather than deleting it.