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:

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.

Buying an eSIM (guest checkout)

The default flow is a simple guest checkout — the customer never has to create an account.

1. Browse by country/region and pick a package (e.g. USA · 5GB · 30 days).
2. Go to Checkout (/checkout).
3. 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).
4. Pay — the customer is redirected to Stripe or PayPal (whichever the store enabled).
5. 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

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.