Reviewers (PMD-3361):

User Story

  • As a Communication Service Provider (CSP) e.g. MVNO, I want to manage batches of IMSIs received from multiple partner MNOs, define eSIM profile templates that specify which IMSIs to include and their priority per roaming zone, and order eSIM profiles from an eSIM provider automatically when a new mobile account is created in PortaBilling, so that my subscribers receive a single eSIM that connects them to the best available network wherever they are, and I am charged the correct wholesale rate per MB for each network used.
  • As an end-user (and frequent traveler), I want seamless connectivity across countries using one plan and balance, so that my service just works wherever I go, with no need to change the SIM card in each country.

Example of use

A travel MVNO operating outside the EU signs wholesale agreements with three partner MNOs:

  • one in the USA (MCC 310)
  • one in Japan (MCC 440)
  • and one in Brazil (MCC 724).

Each partner delivers a batch of IMSIs to the MVNO. The MVNO defines an eSIM profile template called "Global Traveler" that specifies one IMSI from each batch and sets IMSI priority rules per roaming zone based on the per-MB wholesale cost. When a new subscriber signs up and is assigned the "Global Traveler" product, PortaBilling automatically picks one available IMSI from each batch, creates an eSIM record in the SIM inventory, and places an order with orders an eSIM profile from the eSIM provider — a downloadable package containing the selected IMSIs and their roaming priority rules. The subscriber receives a QR code, scans it, and their device is ready to connect — domestically and in all three partner countries — without ever touching a physical SIM card.

Business model

MVNO / MVNE

Technology

  • PortaBilling SIM card inventory — extended to store IMSI batches and multi-IMSI eSIM records
  • IMSI batch — a set of IMSIs received from a single partner MNO, stored in PortaBilling with a configured low-stock threshold and grace period
  • eSIM profile template — a new PortaBilling entity defining that defines which IMSI batches to draw from, how many IMSIs per batch, IMSI priority rules per roaming zone (MCC or MCC+MNC), and behavior when a batch is exhausted
  • eSIM provider (e.g. Nordic eSIM) — GSMA-certified SM-DP+ platform that generates and delivers eSIM profiles upon order from PortaBilling
  • eSIM (eUICC) — a virtual SIM card containing multiple IMSI profiles, delivered to the subscriber as a QR code or activation code
  • eSIM - a virtual SIM card (a physical chip embedded in the device (the eUICC)) that contains multiple eSIM profiles (each of which has an IMSI) which one can download and activate using a QR code or activation code.

Current Solution

PortaBilling's SIM card inventory supports one IMSI per SIM card record. There is no concept of IMSI batches received from partner MNOs, no eSIM profile template, and no automated ordering of eSIM profiles from an eSIM provider. An MVNO wishing to offer multi-IMSI eSIMs must manage IMSI pools, profile composition, and eSIM provider ordering entirely outside PortaBilling, then manually enter the resulting activation code into the SIM inventory. This is error-prone, slow, and does not scale.

Stakeholders and their benefits

Who are the users / whom we bring value to?

Benefit /
Stakeholders		More
Comfort		Increased
Efficiency		Saves
Time		Tighter
Control
CSP / MVNO✔️✔️✔️✔️
End user (subscriber)✔️
✔️

Use Cases

Use case #1: Managing multi-IMSI eSIM lifecycle for a subscriber

Roles: Admin, PortaBilling, eSIM provider (Nordic eSIM), Subscriber

Preconditions: 

  • Three IMSI batches have been uploaded to PortaBilling SIM inventory:
    • Batch "US-Partner" — 500 IMSIs from a US MNO (MCC 310, MNC 150), wholesale price $0.005/MB domestically, $0.012/MB roaming; low-stock threshold: 50 IMSIs; grace period: 30 days
    • Batch "JP-Partner" — 300 IMSIs from a Japanese MNO (MCC 440, MNC 10), wholesale price $0.008/MB domestically, $0.015/MB roaming; low-stock threshold: 30 IMSIs; grace period: 60 days
    • Batch "BR-Partner" — 400 IMSIs from a Brazilian MNO (MCC 724, MNC 05), wholesale price $0.006/MB domestically, $0.014/MB roaming; low-stock threshold: 40 IMSIs; grace period: 45 days
  • All three batches have available IMSIs; none is below its low-stock threshold
  • eSIM profile template "Global Traveler" is configured in PortaBilling:
    • Draw 1 IMSI from "US-Partner", 1 from "JP-Partner", 1 from "BR-Partner"
    • IMSI priority rules per roaming zone: 
      Roaming zoneIMSI priority (1st → 2nd → 3rd)Rationale
      MCC 310 (USA)US-Partner → BR-Partner → JP-PartnerCheapest first
      MCC 440 (Japan)JP-Partner → US-Partner → BR-PartnerCheapest first
      MCC 724 (Brazil)BR-Partner → US-Partner → JP-PartnerCheapest first
      Any other MCCUS-Partner → BR-Partner → JP-PartnerDefault order
    • On batch exhaustion: Proceed with reduced IMSI set
  •  Product "Global Traveler SIM" is configured in PortaBilling, linked to eSIM profile template "Global Traveler", and includes: 
    • A monthly data bundle of 500 600 MB for a flat fee of $25/month
    • A fair usage policy: data speed throttled to 64 kbps once 400 MB is consumed in a billing period, on any network; full speed restored at the start of the next billing period
  • Customer "John Doe" exists in PortaBilling with a valid payment method
  • PortaBilling is integrated with Nordic eSIM and can place eSIM profile orders via API
  • Gy/Ro interfaces are configured between PortaBilling and MVNO for real-time credit control

Use scenario #1.1: New eSIM created and assigned to account (subscriber onboarding)

  • Admin creates a new mobile account for customer "John Doe" with MSISDN `+13015550101` and assigns product "Global Traveler SIM"

  • PortaBilling identifies that the product is linked to eSIM profile template "Global Traveler" and initiates eSIM creation

  • PortaBilling picks one available IMSI from each of the three batches:

    • `310150000000042` from "US-Partner"

    • `440100000000017` from "JP-Partner"

    • `724050000000008` from "BR-Partner"

  • PortaBilling creates a new eSIM record in the SIM card inventory with ICCID `8901310000000000042` containing the three IMSIs, assigns it to account `+13015550101`, and sets eSIM status to Profile ordered
  • The three IMSIs are marked as Reserved in their respective batches; available counts decrease by 1 each:
    • "US-Partner": 499 available
    • "JP-Partner": 299 available
    • "BR-Partner": 399 available
  • PortaBilling sends an eSIM profile order to Nordic eSIM via API, specifying the three IMSIs, MSISDN `+13015550101`, and the IMSI priority rules from the template
  • Nordic eSIM generates the eSIM profile and returns an activation code (QR code) to PortaBilling
  • PortaBilling stores the activation code against eSIM record `8901310000000000042`; eSIM status changes to Available for activation
  • John Doe receives the QR code via email and scans it on his device
  • The eSIM profile is downloaded to John Doe's device; eSIM status changes to In use
  • John Doe's monthly bundle of 500 600 MB is activated; 500 600 MB remaining

Use scenario #1.2: Subscriber connects domestically and roams abroad; fair usage policy applied; bundle renewed

  • Continued after scenario #1.1: eSIM `8901310000000000042` is In use; John Doe has 500 600 MB remaining in his current billing period starting 2026-04-01

  • John Doe's device connects to the US partner network using IMSI `310150000000042` (MCC 310, highest priority for USA)

  • On 2026-04-05, John Doe uses 150 MB of mobile data in the USA

  • PortaBilling produces two charges for the 150 MB session:

    • A wholesale cost entry of $0.75 (150 MB × $0.005/MB, US-Partner domestic rate) representing the amount owed to the US partner MNO

    • A deduction of 150 MB from John Doe's bundle; 350 450 MB remaining

  • On 2026-04-10, John Doe travels to Japan; his device switches to IMSI `440100000000017` (MCC 440, highest priority for Japan)
  • John Doe uses 200 MB of mobile data in Japan
  • PortaBilling produces two charges for the 200 MB session:
    • A wholesale cost entry of $1.60 (200 MB × $0.008/MB, JP-Partner domestic rate) representing the amount owed to the Japanese partner MNO
    • A deduction of 200 MB from John Doe's bundle; 150 250 MB remaining
  • On 2026-04-15, still in Japan, John Doe uses a further 160 MB
  • After the first 150 50 MB of this session, John Doe's bundle reaches the fair usage threshold of 400 MB consumed
  • PortaBilling throttles John Doe's data speed to 64 kbps for the remaining 10 110 MB of this session and for all subsequent sessions in the current billing period, on any network
  • PortaBilling produces two charges for the 160 MB session:
    • A wholesale cost entry of $1.28 (160 MB × $0.008/MB, JP-Partner domestic rate)
    • A deduction of 160 MB from John Doe's bundle; bundle is now at 400 510 MB consumed, 100 90 MB technically remaining but speed-limited
  • On 2026-04-18, John Doe returns to the USA; his device switches back to IMSI `310150000000042` (MCC 310)
  • John Doe attempts to use mobile data; connection is available at throttled speed of 64 kbps (fair usage policy persists across all networks until bundle renewal)
  • On 2026-05-01, the billing period renews; John Doe's bundle resets to 500 600 MB and full data speed is restored on all networks

Use scenario #1.3: Subscriber upgrades product; new eSIM profile generated with updated IMSI set

Additional preconditions:

  • Product "Traveler Gold" exists in PortaBilling, linked to eSIM profile template "Global Traveler Gold", which specifies:
    • Draw 1 IMSI from "US-Partner", 1 from "JP-Partner", 1 from "UK-Partner" (MCC 234, MNC 30, wholesale price $0.004/MB domestically, $0.010/MB roaming; low-stock threshold: 30 IMSIs; grace period: 30 days)
    • A monthly data bundle of 2 GB for a flat fee of $50/month
    • Fair usage policy: throttled to 128 kbps after 1.8 GB consumed; full speed restored at next billing period
    • On batch exhaustion: Proceed with reduced IMSI set
  • Batch "UK-Partner" has available IMSIs and is not below its low-stock threshold
  • John Doe's account `+13015550101` is active with product "Global Traveler SIM" and eSIM `8901310000000000042` in status In use; John Doe has 270 MB remaining in his current bundle

Use scenario 1.3:

  • John Doe requests an upgrade from "Global Traveler SIM" to "Traveler Gold"

  • PortaBilling identifies that "Traveler Gold" is linked to a different eSIM profile template and that a new eSIM profile must be generated

  • PortaBilling picks one available IMSI from each of the three batches specified in "Global Traveler Gold":

    • `310150000000091` from "US-Partner"

    • `440100000000053` from "JP-Partner"

    • `234300000000012` from "UK-Partner"

  • PortaBilling creates a new eSIM record with ICCID `8901310000000000091` containing the three IMSIs, assigns it to account `+13015550101`, and sets its status to Profile ordered
  • The previous eSIM record `8901310000000000042` remains in status In use until the new profile is activated
  • PortaBilling sends the eSIM profile order to Nordic eSIM, specifying the three new IMSIs and their priority rules from template "Global Traveler Gold"
  • Nordic eSIM generates the new eSIM profile and returns a new activation code to PortaBilling
  • PortaBilling stores the new activation code against eSIM record `8901310000000000091`; its status changes to Available for activation
  • John Doe receives the new QR code and scans it on his new device
  • The new eSIM profile is downloaded and activated; eSIM `8901310000000000091` status changes to In use
  • Enabling the new eSIM profile on John Doe's device automatically disables the old profile `8901310000000000042` on the eUICC — only one profile can be enabled at a time (eUICC hardware constraint)
  • PortaBilling notifies Nordic eSIM to retire the old profile for ICCID `8901310000000000042` from their SM-DP+ inventory; Nordic eSIM confirms the old profile record is decommissioned
  • eSIM `8901310000000000042` is  set to Disposed; IMSIs `310150000000042`, `440100000000017`, and `724050000000008` enter a Cooling off state with individual expiry timestamps:
  • eSIM `8901310000000000042` is automatically set to Disposed; IMSIs `310150000000042`, `440100000000017`, and `724050000000008` enter a Cooling off state with individual expiry timestamps:
    • `310150000000042`: cooling off until 2026-05-18 (30-day grace period, US-Partner)
    • `440100000000017`: cooling off until 2026-06-17 (60-day grace period, JP-Partner)
    • `724050000000008`: cooling off until 2026-05-17 2026-06-02 (45-day grace period, BR-Partner)
  • PortaBilling switches John Doe's account to product "Traveler Gold": the remaining 270 MB from the old bundle is discarded, and a new 2 GB bundle is activated pro-rated from the upgrade date
  • John Doe continues using data; subsequent sessions are rated against the new 2 GB bundle and the wholesale rates of the three partner batches per the "Global Traveler Gold" priority rules

Use scenario #1.4: Account terminated before eSIM activation; eSIM profile order cancelled; IMSIs enter grace period and eventually return to available

Preconditions (as in UC #1): John Doe's account `+13015550101` has been created and eSIM `8901310000000000042` is in status Available for activation — the QR code has been issued but not yet scanned.

  • John Doe contacts the MVNO and requests cancellation before activating his eSIM
  • Admin terminates account `+13015550101` in PortaBilling
  • PortaBilling sends a profile cancellation request to Nordic eSIM for the profile associated with ICCID `8901310000000000042`
  • Nordic eSIM confirms the profile has been discarded
  • PortaBilling sets eSIM `8901310000000000042` to status Disposed
  • IMSIs `310150000000042`, `440100000000017`, and `724050000000008` enter Cooling off status with individual expiry timestamps calculated from the disposal date (2026-04-17):
    • `310150000000042`: cooling off until 2026-05-17 (30-day grace period, US-Partner)
    • `440100000000017`: cooling off until 2026-06-16 (60-day grace period, JP-Partner)
    • `724050000000008`: cooling off until 2026-06-01 (45-day grace period, BR-Partner)
  • On 2026-05-17, `310150000000042` automatically transitions from Cooling off to Available in batch "US-Partner"; available count increases by 1
  • On 2026-06-01, `724050000000008` automatically transitions to Available in batch "BR-Partner"
  • On 2026-06-16, `440100000000017` automatically transitions to Available in batch "JP-Partner"
  • All three IMSIs are now available to be picked for new eSIM profiles 

Use scenario #1.5: Lost phone; eSIM profile replaced with fresh IMSIs using the same template

Preconditions: John Doe's account `+13015550101` is active with product "Global Traveler SIM" and eSIM `8901310000000000042` in status In use; John Doe has 200 MB remaining in his current bundle.

  • John Doe reports his phone as lost; Admin triggers an eSIM profile replacement on account `+13015550101`
  • PortaBilling picks one fresh available IMSI from each of the three batches specified in template "Global Traveler":
    • `310150000000105` from "US-Partner"
    • `440100000000061` from "JP-Partner"
    • `724050000000044` from "BR-Partner"
  • PortaBilling creates a new eSIM record with ICCID `8901310000000000105` containing the three new IMSIs, assigns it to account `+13015550101`, and sets its status to Profile ordered
  • PortaBilling sends a profile cancellation request to Nordic eSIM for the old profile associated with ICCID `8901310000000000042`
  • Nordic eSIM confirms the old profile has been disabled
  • PortaBilling sends a new eSIM profile order to Nordic eSIM for ICCID `8901310000000000105`, specifying the three new IMSIs and the priority rules from template "Global Traveler"
  • Nordic eSIM generates the new profile and returns a new activation code to PortaBilling
  • PortaBilling suspends the account's active IMSIs (`310150000000042`, `440100000000017`, `724050000000008`) in the HLR/HSS — the old profile can no longer attach to any partner network immediately
  • PortaBilling notifies Nordic eSIM to retire the old profile for ICCID `8901310000000000042` from their SM-DP+ inventory; Nordic eSIM confirms the old profile record is decommissioned and any further download attempts using the old activation code will be rejected
  • PortaBilling sends a new eSIM profile order to Nordic eSIM for ICCID `8901310000000000105`, specifying the three new IMSIs and the priority rules from template "Global Traveler"Nordic eSIM generates the new profile and returns a new activation code to PortaBilling
  • PortaBilling stores the new activation code; eSIM `8901310000000000105` status changes to Available for activation
  • eSIM `8901310000000000042` is set to Disposed; its three IMSIs enter Cooling off with individual expiry timestamps per their respective batch grace periods
  • John Doe receives the new QR code, scans it on his new phone, and the eSIM profile is downloaded and activated; eSIM `8901310000000000105` status changes to In use
  • John Doe's account, product, and remaining bundle of 200 MB are unaffected by the replacement

Use case #2: IMSI batch stock management

Roles: Admin, PortaBilling

Preconditions:

  • Three IMSI batches are configured in PortaBilling as described in Use Case #1
  • eSIM profile template "Global Traveler" is configured as described in Use Case #1, with on-batch-exhaustion behavior set to Proceed with reduced IMSI set
  • Product "Global Traveler SIM" is linked to template "Global Traveler"

Use scenario #2.1: Batch drops below admin-defined threshold; Admin receives low-stock notification

  • Over the course of several weeks, new subscribers are onboarded and IMSIs are drawn from batch "JP-Partner"
  • The available count in "JP-Partner" drops from 300 to 31 — one above the configured threshold of 30
  • The next subscriber onboarding draws 1 IMSI from "JP-Partner"; available count drops to 30 — exactly at the threshold
  • PortaBilling detects that "JP-Partner" has reached its low-stock threshold and sends a notification to Admin: "IMSI batch JP-Partner has reached the low-stock threshold of 30 IMSIs. Current available count: 30. Please upload additional IMSIs."
  • Admin receives the notification and contacts the Japanese partner MNO to request a new batch of IMSIs
  • No disruption to ongoing onboarding occurs at this stage; the 30 remaining IMSIs continue to be drawn normally

Use scenario #2.2: Batch fully depleted; onboarding proceeds with reduced IMSI set; Admin notified

  • Continued from scenario #2.1: batch "JP-Partner" has 30 IMSIs remaining; Admin has been notified but has not yet uploaded new IMSIs; batches "US-Partner" and "BR-Partner" have ample stock

  • Over subsequent days, 30 more subscribers are onboarded; each draws 1 IMSI from "JP-Partner"

  • "JP-Partner" available count reaches 0; batch status changes to Depleted

  • A new subscriber, "Jane Smith", is onboarded and assigned product "Global Traveler SIM"

  • PortaBilling attempts to pick IMSIs according to template "Global Traveler" and finds "JP-Partner" depleted

  • Since the template is configured with on-batch-exhaustion behavior Proceed with reduced IMSI set, PortaBilling proceeds with the two available batches:

    • `310150000000201` from "US-Partner"

    • `724050000000150` from "BR-Partner"

  • PortaBilling creates a new eSIM record with ICCID `8901310000000000201` containing 2 IMSIs (instead of the usual 3), assigns it to Jane Smith's account `+13015550202`, and sets status to Profile ordered
  • PortaBilling sends the eSIM profile order to Nordic eSIM specifying the two available IMSIs
  • Nordic eSIM generates the profile and returns an activation code; eSIM status changes to Available for activation
  • PortaBilling sends an additional notification to Admin: "Subscriber account +13015550202 was onboarded with a reduced eSIM profile (2 IMSIs instead of 3). Batch JP-Partner is fully depleted. Upload new IMSIs to restore full profile generation."
  • Jane Smith receives the QR code, scans it, and her eSIM is activated with 2 IMSIs; she can connect in the USA and Brazil but not via the Japanese partner network

Wireframes

  • This is an optional section. 
  • Wireframe is a quick illustration of an idea not the prototype itself.
  • Key point is that a final prototype might look completely different after the Solution Design stage.

N/A

Non-functional requirements

  1. Batch IMSI uniqueness: each IMSI must be globally unique across all batches in PortaBilling. An attempt to upload an IMSI already present in any batch must be rejected with an error identifying the conflicting record.
  2. Grace period tracking: each individual IMSI must have its own cooling-off expiry timestamp, calculated at the moment the eSIM it belonged to is disposed. Expiry and return to available status must be handled automatically by PortaBilling without manual intervention.
  3. Low-stock notification timeliness: the low-stock notification must be sent to Admin at the moment the available count in a batch reaches the configured threshold — not batched or delayed.
  4. eSIM provider API resilience: if the eSIM profile order request to the eSIM provider fails (e.g. timeout, API error), PortaBilling must retry automatically and notify Admin if the order cannot be placed after a configurable number of retries.
  5. Bulk upload performance: batch upload of up to 100,000 IMSIs must complete without timeout.

Peculiarities

  1. EU multi-IMSI not applicable: roaming within the EU is free under regulation, so MVNOs and MNOs operating exclusively within the EU have no business case for multi-IMSI eSIMs. This feature is targeted at MVNOs operating outside the EU or offering global/travel services.
  2. Grace period is regulatory: The grace period is a country-level regulatory requirement. For simplicity it is configured per batch rather than per country, which also accommodates cases where two batches from the same country may have different contractual or operational requirements.
  3. IMSI priority vs. network steering: The IMSI priority rules defined in the eSIM profile template determine the order in which IMSIs are listed in the eSIM profile. The actual network selection logic on the device is governed by the SIM applet and device firmware; PortaBilling influences but does not fully control which IMSI is active at any given moment.
  4. Reduced IMSI set and billing: When an eSIM is created with a reduced IMSI set due to batch exhaustion, the subscriber's product, bundle, and billing are unaffected. The reduction is purely at the network access level — the subscriber may have reduced coverage in certain regions.
  5. eSIM profile template vs. product: One eSIM profile template may be shared across multiple products. The template defines the technical composition of the eSIM; the product defines the commercial terms (bundle size, price, fair usage policy). Changes to the template affect all products linked to it.

  6. Multi-IMSI scenarios are MNO-partner (IMSI Sponsor) dependent and vary among Gy/Ro/Mediation scenarios. Based on that multiple types of identifiers can be used to 

    1. Identify account either using Subscription-Id or User-Name AVP

      • <IMSI>@imsi
      • <MSISDN>@msisdn

    2. Identifying user connected (home/roaming) network:

      • Service-Information → PS-Information → 3GPP-User-Location-Info (Gy), holds CGI of subscriber, starting with roaming MCCMNC

      • Service-Information → PS-Information → 3GPP-SGSN-MCC-MNC (Gy)
      • Service-Information → IMS-Information → IMS-Visited-Network-Identifier (Ro), e.g. 'ims.mnc099.mcc460.3gppnetwork.org'
    3. Identifying the IMSI sponsor and make above choice in AAA interconnection
      • Origin-Host

Performance / Clustering, Geo Redundancy/ Dual-Version, Porter / Call Control API

  • Multi-IMSI eSIM management and eSIM provider API integration must function correctly in both standalone and dual-version (depending on implementation but something similar to SIM inventory synchronization) PortaSwitch configurations
  • Grace period expiry processing must be resilient to system restarts — expiry timestamps must be persisted and processing must resume correctly after any downtime.

 ESPF / Monitoring

  • Admin must be able to monitor the current available count, reserved count, cooling-off count, and depleted status of each IMSI batch from the PortaBilling interface.
  • Failed eSIM profile orders (after exhausting retries) must generate a monitoring alert visible to PortaOne support.