eSIM Inventory Management

This guide explains how to configure eSIM inventory for different distribution channels — digital (online) versus printed (physical cards).

See also: Inventory <administration_inventory> for general inventory management, SIM Card Provisioning <concepts_sim_provisioning> for provisioning workflows and the eSIM issuer API.

Overview

eSIMs can be distributed through two channels:

1. Digital Distribution — Issued instantly via the self-signup portal, delivered by email with QR code
2. Printed Distribution — Pre-printed on cardboard cards for physical handout or retail sale

The item_location field in the Inventory table controls which channel an eSIM is available for.

Distribution Channel Configuration

The item_location field determines how an eSIM can be distributed:

Value	Description	Available Via
digital	Available for online/instant issuance	Self-signup portal, API
printed	Reserved for physical card distribution	Manual assignment only
Other values	Not available for automatic issuance	Manual assignment only

Setting Up Digital eSIMs

To make eSIMs available for online distribution:

1. Navigate to Inventory in OmniCRM
2. Select the eSIM inventory items intended for digital distribution
3. Set item_location to digital
4. Save changes

Setting Up Printed eSIMs

For eSIMs that have been printed on physical cards:

1. Navigate to Inventory in OmniCRM
2. Select the eSIM inventory items that are printed
3. Set item_location to printed (or any value other than digital)
4. Save changes

How Digital Issuance Works

When a customer requests an eSIM through the self-signup portal via POST /crm/oam/issue-esim:

1. The API queries inventory for available eSIMs
2. Only eSIMs matching all of the criteria below are considered
3. One eSIM is randomly selected from the available pool
4. The eSIM details are sent to the customer via email

Inventory Selection Criteria

Field	Condition	Purpose
item	Contains "esim" (case-insensitive)	Identifies eSIM inventory items
item_location	Equals digital	Restricts to digital distribution channel
customer_id	Is null	Not yet assigned to a customer
service_id	Is null	Not yet assigned to a service

For full details on the issue-esim endpoint including request parameters, rate limiting, and error responses, see SIM Card Provisioning - Public eSIM Issuer API <concepts_sim_provisioning>.

Error Handling

If no digital eSIMs are available, the API returns:

HTTP Status	Error Type	Message
503	NoInventory	"No eSIMs currently available. Please try again later or choose a physical SIM."

Key Inventory Fields for eSIMs

Field	Type	Description
item	String	Item type identifier (must contain "esim" for eSIM items)
item_location	String	Distribution channel: digital for online, other values for physical
itemtext1	String	ICCID — the unique eSIM identifier
management_url	String	LPA activation string (e.g., LPA:1$rsp-eu.simlessly.com$...)
customer_id	Integer	Assigned customer (null if unassigned)
service_id	Integer	Assigned service (null if unassigned)

For a complete reference of all inventory item fields, see Inventory - Inventory Item Fields <administration_inventory>.

Automatic Import from HSS

When SIMs are imported from the HSS using the provisioning script, two fields are set automatically based on the HSS record:

Distribution Channel (item_location):

• If the batch name contains "digital" (case-insensitive), the eSIM is marked as item_location = 'digital' for online distribution
• Otherwise, the eSIM is set to the default physical location (e.g., "Ascension Island")

LPA Activation String (management_url):

• The lpa field from the HSS SIM record is automatically imported as management_url
• This enables QR code generation in the CRM for eSIM activation
• If the HSS record has no lpa value, the eSIM is imported without an activation string

This means distribution channel and LPA data can be controlled at the HSS level:

• Name batches appropriately (e.g., "Digital eSIMs Q1 2026", "Printed Cards Batch 3")
• Ensure eSIMs have their lpa field populated in the HSS before import

Best Practices

Inventory Segregation

• Keep digital and printed eSIM pools separate using item_location
• Monitor digital pool levels to ensure availability for self-signup customers
• Consider setting alerts when digital eSIM inventory runs low

Manual Batch Updates

When manually importing or updating eSIMs:

1. Digital eSIMs: Set item_location = 'digital' during import
2. Printed eSIMs: Set item_location = 'printed' or the physical location (e.g., "Georgetown Office")

Converting Between Channels

To move eSIMs between channels:

• Printed to Digital: Update item_location from printed to digital
• Digital to Printed: Update item_location from digital to printed (only if not yet issued)

Troubleshooting

No eSIMs Available for Online Issuance

Symptoms: Customers see "No eSIMs currently available" when requesting an eSIM online.

Possible causes:

• No eSIMs have item_location set to digital
• All digital eSIMs are already assigned (both customer_id and service_id are non-null)
• eSIM items don't have "esim" in the item name

Resolution:

1. Check inventory for eSIMs with item_location = 'digital'
2. Verify there are unassigned eSIMs (both customer_id and service_id are null)
3. Add more eSIMs to the digital pool or convert printed ones if available

Printed eSIMs Being Issued Online

Symptoms: eSIMs intended for physical cards are being issued through the portal.

Possible causes:

• item_location not set correctly on printed eSIMs

Resolution:

1. Update all printed eSIMs to have item_location = 'printed'
2. Ensure new printed eSIM imports set the correct item_location value