Getting the Product List

The first step when integrating to the MobiMatter API is to fetch the products. MobiMatter's eSIM products are all pre-packaged, and are differentiated by provider, data allowance, package validity and country coverage.

Products are differentiated by the productCategory attribute on the product model.

Product Categories

ProductCategory	Description
esim_realtime	New eSIM sales. All products under this category will return a new QR code with the specific package assigned to it.
esim_addon	eSIM Topups. All products under this category will add the package onto an existing eSIM previously bought with MobiMatter of the same provider. See Finding Top-up Products.
esim_replacement	eSIM replacements. All products under this category will return a new QR code, and assign the existing package from an eSIM previously bought with MobiMatter of the same provider. See Issuing eSIM Replacement.
esim_delayed	KYC eSIMs. These products require the customer to complete identity verification before the eSIM is activated, so the order completes asynchronously and returns a KYC_URL for you to share. This is the only category that returns a KYC_URL. See Placing an Order.

Product Families

Each product is assigned a productFamilyId, this value will allow you to determine which packages you can interchangeably top-up. In other words, if two products share the same product family, you can top-up one with the other.

Product Availability

There is no stock, status or availability field on the product model.

If a product you previously sold stops appearing in the response, it has been unassigned or withdrawn and should be deactivated in your own catalogue. Take care to distinguish this from a failed request: a non-2xx response or a network error is not an empty catalogue, and treating it as one would deactivate everything you sell.

Product response caching

Each product has an updated field, which denotes when was this product last updated. This field can be useful to cache product definitions on your end, and bust the cache when the product is updated again.

Example Request

curl -L "https://api.mobimatter.com/mobimatter/api/v2/products" -H "api-key: xyz" -H "MerchantId: deadbe-eef5-75AC-1A5F-69C92154013b"

Example Product

{
    "productId": "49951e61-dead-beef-9f8b-69b94975509b", 
    "rank": 42667, // A MobiMatter quality factor, higher is better. Can be useful for product sorting by quality.
    "productCategoryId": 1, 
    "productCategory": "esim_realtime", // see above table
    "providerId": 22, 
    "networkListId": 1,
    "providerName": "Vinaphone",
    "providerLogo": "https://mobimatterstorage.blob.core.windows.net/mobimatter-assests/assets/vinaphone.png",
    "retailPrice": 8.99, // Merchant's set retail price, can be adjusted in the Partner Portal
    "wholesalePrice": 7.6, // Merchant's cost for this product, this amount will be deducted from the wallet when purchasing
    "currencyCode": "USD", // USD only transactions are supported
    "created": "2023-02-20T15:53:38.107Z",
    "updated": "2023-06-20T04:36:41.5249522Z", // Last update to this product, useful for caching
    "regions": [
        "Asia"
    ],
    "countries": [ // ISO 2-letter country codes for country coverage
        "VN"
    ],
    "displayAttributes": [],
    "productDetails": [
        {
            "name": "PLAN_TITLE",
            "value": "Vietnam 60 GB"
        },
        {
            "name": "PLAN_DATA_LIMIT",
            "value": "60"
        },
        {
            "name": "PLAN_DATA_UNIT",
            "value": "GB"
        }
        {
            "name": "PLAN_VALIDITY", // In hours
            "value": "360"
        },
        {
            "name": "TAGS",
            "value": "[{\"color\":\"#464545\",\"item\":\"BEST QUALITY\"}]"
        },
        {
            "name": "PLAN_DETAILS",
            "value": "{\"heading\":\"BEST DEAL - LOCAL VIETNAM eSIM FOR TOURISTS\",\"description\":\"Usage limitation: 4GB per day for 15 days.\",\"items\":[\"Tourist eSIM package from Vietnamese mobile operator Vinaphone. Voice calls or SMS is not included.\",\"The bundle contains 4GB per day of high-speed data for 15 days.\",\"Connects to Vinaphone network with 4G LTE speeds.\",\"Validity of the package will start upon scanning the QR code and downloading the eSIM to your phone.\",\"Unlimited data - if 4GB daily allowance is fully consumed the line will continue to work with throttled speeds until the next day.\",\"Simply scan the QR code to download and use the eSIM. No other activation or registration steps needed.\",\"One time prepaid package. No auto-renewals, no contracts.\",\"Usable only with eSIM compatible phones and tablets which are not carrier locked. If in doubt, please check the FAQ section.\",\"Please start using the eSIM no more than 1 month after purchase.\"]}"
        },
    ]
}

Product Details Reference

The productDetails array holds the plan's display and packaging information as { name, value } pairs. All values are strings. Parse these once when you sync the product, not on every page render.

Name	Value
PLAN_TITLE	Display title of the plan, e.g. Vietnam 60 GB.
PLAN_DATA_LIMIT	Numeric data amount, e.g. 60.
PLAN_DATA_UNIT	Unit for the value above, e.g. GB.
PLAN_VALIDITY	Package validity in hours. 360 means 15 days.
PLAN_DETAILS	A JSON string containing { heading, description, items[] }. Parse the field, then parse its value.
TAGS	A JSON string containing [{ color, item }], for display badges such as BEST QUALITY.

Not every key is present on every product. Look values up by name rather than relying on array position.

Getting the networks that a products connects to

Click for relevant API endpoint

Each product that has network information will have a networkListId attribute. This ID identifies the set of mobile networks that this eSIM product can connect to. You can query the product's networks and retrieve detailed information about available networks.

Making a Network List Request

To retrieve the networks for a specific product, use the following endpoint:

curl -L "https://api.mobimatter.com/mobimatter/api/v2/products/{productId}/networks" \
-H "api-key: YOUR_API_KEY" \
-H "MerchantId: YOUR_MERCHANT_ID"