Storefront & customers
This guide is for the buyer side of esimScan: the public storefront where customers browse and purchase eSIMs, how an eSIM is delivered, and the optional customer account.
The storefront (/)
The storefront is public — no login is required to browse or buy. It surfaces the store’s synced catalog:
| Page | Route | Purpose |
|---|---|---|
| Home | / | Hero, search, featured destinations and packages |
| Destinations | /destinations | Browse eSIMs by country |
| Destination detail | /destination/{slug} | Packages for one country/region with prices |
| Popular packages | /popular-packages | Highlighted best-sellers |
| All-in-One plans | /all-in-one-plans | Multi-country / regional bundles |
| Pricing & info | /why-choose-us, /about, /blog, /gift-cards | Marketing pages |
| Legal | /terms, /privacy | Terms and privacy |
Prices reflect the store’s margin on top of the provider wholesale cost, shown in the visitor’s selected currency.
AI eSIM Advisor (if enabled)
When the store owner has enabled it, a floating AI Advisor button appears at the bottom-right of every storefront page (with a short greeting on first load). A shopper can describe their trip in plain language — e.g. "Japan for 10 days, Maps and Instagram daily" — and get a few matching plans from this store's catalog, each with a one-line reason and a Buy now button into checkout. See the AI assistant guide for how it's configured.
On the phone
Everything in this guide is the web experience. The same store is also available as a native Android and iOS app — see the mobile app guide. Customers sign in there with the same account they use at /login, and orders placed in either place show up in both.
Buying an eSIM (guest checkout)
The default flow is a simple guest checkout — the customer never has to create an account.
- Browse by country/region and pick a package (e.g. USA · 5GB · 30 days).
- Go to Checkout (
/checkout). - Enter details — email and phone, accept terms. Optionally enter a voucher or gift-card code — the discount is validated and applied live (
/checkout/apply-code). - Pay — the customer is redirected to Stripe or PayPal (whichever the store enabled).
- Receive the eSIM — on success (
/checkout/success) the order is recorded and, once fulfilled, the customer is emailed a QR code and install instructions.
The customer’s email is saved automatically as a customer record so the store can support them, even though guest buyers have no dashboard.
How the eSIM is delivered
After payment, the order moves through its lifecycle:
PAID ─▶ PROVISIONING ─▶ FULFILLED ─▶ DELIVERED
(money taken) (ICCID + QR ready) (QR emailed)
What happens at PROVISIONING depends on the store’s fulfillment mode:
- Manual — staff prepare and deliver the eSIM from the panel.
- Stub — demo eSIM data is generated instantly (testing only).
- Live — the provider API issues a real eSIM automatically.
The delivery email contains a scannable QR code plus manual details (SM-DP+ address and activation code). The QR image is served from a signed URL (/esim/qr/{order}) embedded in the email and order views. Delivery requires an active SMTP configuration (Admin → Email System); without it, the order still fulfills but no email is sent.
If a customer doesn’t receive the email, you can resend it from the order in admin, or fulfill manually if provisioning failed.
Vouchers and gift cards
Codes created in Admin → Marketing are redeemable at checkout:
- Vouchers — discount codes (percentage or fixed amount).
- Gift cards — prepaid balance codes.
Codes are re-validated server-side at checkout; the charge is reduced and usage/balance is tracked automatically.
Customer account (optional)
Buyers can register for a customer account to keep their eSIMs and orders in one place. This is separate from the admin login.
- Register / Sign in:
/register,/login. Email/password, with password reset (/forgot-password), or Sign in with Google when the store has enabled social login. - Account area:
/account
| Area | Route | Purpose |
|---|---|---|
| Dashboard | /account/dashboard | Overview of recent eSIMs and orders |
| My eSIMs | /account/esims | Issued eSIMs with QR/activation details (/account/esims/{order}) |
| Orders | /account/orders | Purchase history |
| Profile | /account/profile | Name, email, password |
| Identity (KYC) | /account/kyc | Submit verification documents; uploads stream from a private disk |
| Notifications | /account/notifications | In-app alerts |
| Support | /account/support | Raise and reply to support tickets |
Identity verification (KYC)
Some regions or packages may require identity verification. Customers submit documents under Account → Identity; documents are stored on a private disk and reviewed in admin (approve or reject). See the Admin guide for the review side.
Language and currency
The storefront is multi-language (including RTL locales such as Arabic) and multi-currency. Visitors switch language and display currency from the storefront controls; the selection is remembered for the session. Available locales and currencies are configured by the admin.
Demo deployments
If the store runs with APP_DEMO_MODE=true, the back-office is read-only, but the storefront still browses normally. Checkout is also guarded in demo mode, so test orders may be blocked — see Setup → Demo mode.