Provider feed guide

Three things to know first

• 1

  Nothing here changes rankings. Plans are ordered by price and data only, and a richer feed never buys a better position — it only fills in facts travellers can filter and read. See how we rank. How we rank →

• 2

  If you already publish a standard DataPlan feed for other comparison sites, you are done with the required and recommended fields. The eSIMKart extras sit under one extra key and never collide with what you emit today.

• 3

  Unknown is never shown as "none". A fact your feed does not state is rendered as "Not stated", not as "not supported" — so leaving a field out is always safe.

The three tiers

Plan feed — field by field

One JSON array, one object per plan. The "You get" column is the exact place on eSIMKart the field fills.

Fields we read but deliberately ignore

Promo flags (newUserOnly, firstPurchasePromo, promoEnabled, priceInfo) never change the listed price — we show the steady-state price a returning customer pays. Put a code that is exclusive to eSIMKart readers in the provider profile instead; we show it on every row with a one-click copy. webUrl is read only when link is missing; sku only when id is missing.

Example plan feed

[
    {
        "id": "es-5gb-15d",
        "planName": "Spain 5 GB / 15 days",
        "coverages": [
            {
                "code": "ES",
                "networks": [
                    {
                        "name": "Movistar",
                        "types": [
                            "4G",
                            "5G"
                        ]
                    },
                    {
                        "name": "Orange",
                        "types": [
                            "4G"
                        ]
                    }
                ]
            }
        ],
        "dataCap": 5,
        "dataUnit": "GB",
        "dataCapPer": "",
        "validity": 15,
        "prices": {
            "USD": 9.9,
            "EUR": 9.2,
            "GBP": 7.9
        },
        "link": "https://example-esim.com/plans/spain-5gb-15d?ref=esimkart",
        "tethering": true,
        "canTopUp": true,
        "telephony": null,
        "eKYC": false,
        "activationInfo": "Validity starts on first network connection.",
        "additionalInfo": "Install within 365 days of purchase.",
        "subscription": false,
        "payAsYouGo": false,
        "esimkart": {
            "activation": "first_use",
            "installWithinDays": 365,
            "voiceMinutes": 0,
            "smsCount": 0
        }
    },
    {
        "id": "es-unl-7d-1gb",
        "planName": "Spain Unlimited / 7 days (1 GB/day high-speed)",
        "coverages": [
            {
                "code": "ES",
                "networks": [
                    {
                        "name": "Movistar",
                        "types": [
                            "4G",
                            "5G"
                        ]
                    }
                ]
            }
        ],
        "dataCap": 1,
        "dataUnit": "GB",
        "dataCapPer": "day",
        "reducedSpeed": 512,
        "capacityInfo": "1GB of high-speed data per day, then reduced to 512 Kbps",
        "validity": 7,
        "prices": {
            "USD": 14.5
        },
        "link": "https://example-esim.com/plans/spain-unlimited-7d?ref=esimkart",
        "tethering": true,
        "canTopUp": false,
        "eKYC": false,
        "esimkart": {
            "fairUsage": {
                "dailyCapMb": 1024,
                "throttleKbps": 512
            },
            "activation": "first_use",
            "installWithinDays": 180,
            "maxSpeedKbps": 100000
        }
    }
]

Unlimited plans, done right

This is the section most feeds get wrong, and the one travellers filter on most. Three encodings are accepted, in order of preference:

1. 1.The fairUsage extension: {"dailyCapMb": 1024, "throttleKbps": 512} or {"uncapped": true}. Nothing to parse; what you send is what shows.
2. 2.dataCap + dataCapPer "day" + reducedSpeed: {"dataCap": 1, "dataUnit": "GB", "dataCapPer": "day", "reducedSpeed": 512}.
3. 3.A capacityInfo sentence. We parse the shapes below; anything else shows as "Not stated" rather than a guess.

"Not stated" and "No daily cap" are different things on eSIMKart. We only write "No daily cap" when the feed says so explicitly (fairUsage {uncapped: true}, or a sentence like "no daily cap"). dataCap 0 on its own means unlimited with the limits unknown — it shows as Unlimited with the daily cap "Not stated". A known daily allowance with an unknown speed after it: dataCap + dataCapPer "day" without reducedSpeed — the cap shows, After cap stays "Not stated". Silence stays "Not stated".

Regional and global bundles

• A plan whose coverages array lists two or more countries becomes one bundle row with every member country attached; it appears on each member's destination page and on the region and global lanes.
• A stable id matters even more here — bundle rows are keyed by it. Without one we hash the name, days, cap and country list, and a renamed bundle looks like a new plan.
• Bundles covering 50 or more countries are treated as global.
• Network lists are only read for single-country plans; a bundle's networks cannot be attributed to the right country.

Prices and promotions

• Send the steady-state price. Launch offers and first-purchase discounts are ignored so that the site never shows a price a returning customer cannot get.
• A discount code that is exclusive to eSIMKart readers goes in the provider profile (discountCodes) — we show it on every plan row with one-click copy and on the coupons page. A public campaign anyone can find is a Deal: we list it, it never affects the price shown.
• USD is used as sent. Other currencies are converted with our daily rate; if you can, send USD alongside so the listed price is exactly yours.

Provider profile

One JSON object per provider for the facts the plan feed cannot carry: the 12-fact trust card, networks per country, contact addresses, logos and any code exclusive to eSIMKart. We verify every trust fact against your public pages before it goes live and never ingest this file automatically — it simply makes that verification a day instead of a week.

Example provider profile

{
    "name": "Example eSIM",
    "website": "https://example-esim.com",
    "legalEntityName": "Example Mobile Ltd",
    "headquarters": "London, United Kingdom",
    "foundedYear": 2021,
    "refundPolicy": {
        "text": "Full refund within 30 days if the eSIM has not been installed; technical failures we confirm are refunded at any time.",
        "url": "https://example-esim.com/refund-policy"
    },
    "validityPolicy": "Validity starts on first network connection, not at purchase.",
    "fairUsePolicy": "Unlimited plans include a daily high-speed allowance stated on each plan; speed is reduced, never cut off, until the next day.",
    "topUpPolicy": "Every plan can be topped up from the account page while it is still valid.",
    "reissuePolicy": "A deleted eSIM can be re-issued once by support if it has not been activated; after activation a new plan is needed.",
    "billingCurrencyNote": "Charged in USD; EUR and GBP prices are shown at checkout and charged in that currency, no conversion fee.",
    "supportChannels": [
        "live_chat",
        "email",
        "whatsapp"
    ],
    "supportHours": "24/7 in English and Spanish",
    "paymentMethods": [
        "card",
        "paypal",
        "apple_pay",
        "google_pay"
    ],
    "kycRequired": false,
    "multiDevicePolicy": "One eSIM per purchase, installable on one device; buy several plans under one account.",
    "dataExpiryPolicy": "Unused data is lost when the plan expires; a top-up before expiry keeps it.",
    "networks": [
        {
            "country": "ES",
            "networks": [
                {
                    "name": "Movistar",
                    "types": [
                        "4G",
                        "5G"
                    ]
                }
            ]
        }
    ],
    "contactEmails": [
        "[email protected]"
    ],
    "logos": {
        "logo": "https://example-esim.com/brand/logo-wide.png",
        "icon": "https://example-esim.com/brand/icon-square.png",
        "favicon": "https://example-esim.com/favicon.png"
    },
    "discountCodes": [
        {
            "code": "ESIMKART10",
            "percent": 10,
            "type": "first_payment",
            "endsAt": null,
            "exclusiveToEsimkart": true
        }
    ],
    "deals": [
        {
            "title": "Summer sale: 20% off every Europe bundle",
            "url": "https://example-esim.com/summer",
            "startsAt": "2026-06-01",
            "endsAt": "2026-08-31"
        }
    ]
}

Recommended URL

Any URL works. If you are creating a new endpoint for us, this naming keeps the ref parameter and the extensions in one obvious place, next to the feeds you may already publish for other sites:

Plan feed

https://{your-domain}/api/esimkart/data-plans?ref=esimkart

Provider profile

https://{your-domain}/api/esimkart/provider.json

Optional query parameters we understand: ccy=USD,EUR (which currencies to include) and ref= (we pass through whatever tracking value you put on link).

Delivery

• A public URL is ideal (a static JSON file refreshed at least daily is fine). Authentication we support: none, a static header or query key, or OAuth client credentials.
• We fetch nightly — one request for the plan feed. ETag or Last-Modified headers are welcome, not required.
• If your edge challenges bots, allow our fetch addresses at the edge (for Cloudflare: a WAF rule that skips managed challenges for those IPs). An allowlist inside your application is not enough — a challenge page is returned before the request reaches it. We send our fetch addresses when you reply; they are not published here.
• Send the URL and, if any, the credentials to [email protected] or through the partner form. Existing partners can also open a support ticket from the portal.

Changelog

• 2026-09-11 · First version: standard DataPlan fields, eSIMKart extensions (voiceMinutes, smsCount, phoneNumber, fairUsage, activation, installWithinDays, kyc, maxSpeedKbps), provider profile.
• 2026-09-11 · Done-for-you feed setup added: one-time fee, free with a Partner Insights seat.
• 2026-10-04 · phoneNumber accepts a list (several numbers, or choose: true when the buyer picks one) and false for "no number"; the number's country now decides "Local number" in the local-number lane.