Tellgo

Everything went in through Medusa's own extension points — services, subscribers, routes, scheduled jobs, models and migrations. The engine underneath stays a dependency we can upgrade, not a codebase we now own.

An hourly job reads the supplier's countries, operators and packages and upserts them as collections, products and variants, each stamped with the provider that owns it. The merchandising team's job becomes pricing and presentation, not data entry, and a supplier adding a country shows up in the store within the hour.

Adding a second supplier started as a schema problem, not an integration problem. One migration renames airalo to esim_data, renames airalo_order_id to provider_order_id, and adds a provider enum defaulting to airalo — so every row already in the table answers the new question correctly the moment the column exists. A second backfills the same default across the catalogue. Both have a working down(). None of it was clever; the point is that it was reversible.

Ordering and authentication are separate interfaces, because suppliers differ more in how they let you in than in what they sell. Airalo speaks OAuth2 client-credentials; eSIM Card wants a reseller email and password. Both tokens cache in Redis for a day, and both providers recognise their own expiry from a failed response rather than trusting a clock — Airalo, in practice, by treating a 525 as expired as well as a 401. The rest of the system asks for a provider and gets one.

Provisioning is attempted inline, but a supplier that does not answer immediately must not become a failed order. The order records a pending marker instead, and a job every five minutes resolves it against the right supplier. The customer sees a plan that arrives shortly rather than a checkout that broke.

The two suppliers disagree about how an activation code arrives: one returns a QR image, the other returns the raw LPA string. Rather than normalise that server-side and lose fidelity, the app renders the code itself at 512 pixels when it gets a string and displays the image when it gets one. The adapter pattern that keeps the backend supplier-agnostic shows up again on the client, for the same reason.

The reason to keep inventory is so you never sell what you cannot deliver. An eSIM has no inventory, but the reseller account behind it has a balance, so that is where the check goes: before checkout completes, the supplier's balance is compared against net price times quantity. If it is short the customer gets a plain "not available right now" — not a successful order that quietly never arrives.

Airalo and eSIM Card sit behind a common interface. Their APIs disagree about almost everything — response shapes, auth, how a package is described — and none of that reaches the rest of the system, which sees one normalised view of a plan, an order and a usage reading. Browsing is by country or continent, mapped to catalogue handles, with a global package for people crossing several.

The hourly importer keeps thousands of plans in step with the suppliers, creating and updating collections, products and variants. Because plans are ordinary Medusa products, they merchandise, discount, translate and report exactly like the headphones sold beside them.

On payment the plan is bought and the customer gets the QR and install instructions in their account, alongside what is left on the plan, queried live against whichever supplier issued it. Anything the supplier has not returned yet is picked up by the five-minute job and completed without anyone being asked to try again.

A stored-value wallet and a separate loyalty currency, both spendable at checkout, both derived from a transaction ledger rather than a mutable balance field. Medusa has neither concept, so both are services with their own models, admin screens, reports and line on the receipt.

A single order can draw on card, wallet, loyalty points, gift voucher and discount at once, each carried separately through to the receipt. That separation is what makes reconciliation possible later.

MyFatoorah in Kuwaiti dinar on both web and app, because that is what customers in the GCC expect at checkout. Every order renders a PDF invoice through headless Chrome, stores it on S3 and mails it via SES with every tender itemised.

Titles, subtitles and descriptions carry a language and are unique per product and language, with the storefront routed under a language segment. The Arabic store is a real store, not a machine-translated shadow of the English one.

One Flutter codebase for iOS and Android, now at version 3, structured as a service locator over repositories with a service and controller per domain. Firebase auth with Google, Facebook and Apple sign-in; push through Firebase Messaging; profile photos picked, cropped and compressed on the device rather than shipped full-size to the server.

The activation screen renders the eSIM QR locally, so a traveller who has landed without data can still install the plan they bought before they took off.

Version enforcement is the part that took real work, because the two platforms do not offer the same thing. Android uses Play's In-App Update API and knows how to resume an update the user abandoned halfway. iOS has no equivalent, so the app asks the App Store what version is live and prompts from there — and deliberately stays quiet when the store reports a build that is still in review, so nobody is told to update to something they cannot download. Every failure path in that check falls through to the login screen. A version check is never a reason to lock someone out of an app that holds their money.

An extended Medusa admin covering eSIM products and orders, wallets, offers, banners, promotional email and reporting, with widgets putting the ICCID and payment reference on the order screen where support actually needs them. Backend deploys are a button the team presses when it is ready, not something that fires on merge; the iOS build runs in GitHub Actions.

Provisioning hangs off payment rather than order placement, so a checkout that never pays never buys a real plan. The cost is a slightly later delivery. The alternative is paying a supplier for orders that never complete.

The tempting version is an if statement and a second column. We did the migration instead: rename the table, rename the join, add an enum defaulting to what is already true, backfill the catalogue, keep a down(). More work up front, and the reason a third supplier is a class rather than a refactor.

A pending SIM is a row a cron can find, not a request holding a connection open. It means the checkout returns quickly, a supplier outage resolves itself when the supplier comes back, and the state of every unfinished order is a query rather than a guess.

Checking whether an app is current means calling something that can fail — a store API, a network, a plugin. Every one of those paths ends at the login screen rather than a dead splash. The customer with money in a wallet gets into the app even on the day the update check is broken.

The pipeline builds and ships on demand rather than on merge, so a merge to release is a decision to be ready and pressing deploy is a decision to go. For a store taking real payments in a single market, that separation is worth the extra click.