Skip to main content

Finding Top-up Products

Once a customer owns an eSIM, you can sell them more data for it by ordering an esim_addon product against their existing order. This guide covers how to find which top-up products are valid for a given eSIM.

The rule​

A top-up product can be applied to an eSIM only if both share the same productFamilyId.

That value is on every product in the Get Products response, and on the orderLineItem of every order. So finding the valid top-ups for an eSIM is a two-step lookup: read the family, then query the family.

1. Find the eSIM's product family​

If you stored the product's productFamilyId when you synced your catalogue, use that. Otherwise read it back from the original order:

curl -L -X GET 'https://api.mobimatter.com/mobimatter/api/v2/order/XYZ-234323' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>'

The family is on the line item:

{
  "statusCode": 200,
  "result": {
    "orderId": "XYZ-234323",
    "orderState": "Completed",
    "orderLineItem": {
      "productId": "c0654cf2-0172-4909-91d1-37ca37e6f195",
      "productCategory": "esim_realtime",
      "productFamilyId": "5",
      "productFamilyName": "3HK Global",
      "title": "Global 13 GB"
    }
  }
}

2. Query the family for top-up products​

Pass both category=esim_addon and the familyId you just read:

curl -L -X GET 'https://api.mobimatter.com/mobimatter/api/v2/products?category=esim_addon&familyId=5' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>'

Every product returned is a valid top-up for that eSIM. If the response is empty, this family has no top-up products assigned to your account, and you should not offer top-ups for it.

Filtering by familyId alone is not enough — without category=esim_addon you will also get the esim_realtime and esim_replacement products in the family, which are not top-ups.

3. Check the eSIM can actually be recharged​

Some eSIMs cannot accept top-ups even when compatible products exist. Before showing top-up options, check the rechargeable flag from Get Usage Information:

{
  "orderId": "XYZ-234323",
  "planName": "Global 13 GB",
  "rechargeable": true
}

If rechargeable is false, do not offer top-ups for that eSIM.

caution

Check rechargeable before you display the top-up options, not just before you create the order.

If you list top-ups for an eSIM that cannot accept them, the customer picks one and pays you, and the order then fails — leaving you to refund them. The check belongs on the screen that shows the options, not on the button that submits them.

note

The usage endpoints reach through to the provider's own systems. Call them when a customer takes an action — such as opening the top-up screen — and cache the result briefly. Do not poll them on a timer or prefetch them for a list of eSIMs.

4. Order the top-up​

Create the order with productCategory: "esim_addon" and addOnOrderIdentifier set to the original eSIM order id, then complete it exactly as you would a new sale.

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_addon",
  "addOnOrderIdentifier": "XYZ-234323",
  "label": "your-internal-ref"
}'
caution

addOnOrderIdentifier is always the original eSIM order — never the most recent top-up, and never a previous replacement.

XYZ-234323   esim_realtime      the original purchase
XYZ-234400   esim_addon         addOnOrderIdentifier: XYZ-234323
XYZ-234511   esim_addon         addOnOrderIdentifier: XYZ-234323   (not XYZ-234400)
XYZ-234690   esim_replacement   addOnOrderIdentifier: XYZ-234323
XYZ-234712   esim_addon         addOnOrderIdentifier: XYZ-234323   (not XYZ-234690)

Store the original order id against the customer's eSIM once, when they first buy, and never reassign it.

Offering top-ups in your own catalogue​

Because productFamilyId is stable, you do not need to run steps 1 and 2 at request time. When you sync your catalogue, group products by productFamilyId and store the mapping. Then a customer's top-up options are a local lookup, and the only live calls at purchase time are the rechargeable check and the order itself.