Core concepts
eSIM lifecycle
From provisioning to activation to expiry.
An eSIM has two state machines, not one. status tracks the profile on the
device (the SM-DP+ side); lifecycleStatus tracks the IMSI on the
network (whether the line is allowed to work). Both come back on every eSIM
read, though lifecycleStatus is null until the eSIM is assigned to a
profile.
Profile status
status | Meaning |
|---|---|
released | Created and reserved. An activation code exists but nothing is installed. |
downloaded | A device has fetched the profile. |
installed | The profile is installed on the device. |
enabled | The profile is active on the device. This is "working data". |
disabled | Installed but switched off on the device. |
deleted | Removed from the device. |
faulted | Something went wrong. Contact support with the esimReference. |
The middle five happen on the device, not through the API: released is set
when you order, and faulted is reported. You observe the device ones via
webhooks (esim.downloaded,
esim.installed, esim.enabled, ...) or by polling the eSIM.
Service lifecycle
lifecycleStatus | Meaning |
|---|---|
preactive | Provisioned, not yet active on the network. |
active | Active and connected. |
suspended | Temporarily suspended. Reversible. |
terminated | Permanently ended. Terminal. |
faulted | Provisioning failed. Contact support with the esimReference. |
stale | Configuration mismatch, for example the wrong base plan. |
preactive is where a new eSIM starts. You move it from there with the
lifecycle endpoint, which takes three operations: suspend, reactivate and
terminate. faulted and stale are reported to you rather than requested,
and both need support to clear.
Suspension is the only reversible one; terminate cannot be undone, which is why the CLI makes you confirm it by typing the last four digits of the eSIM reference.
Validity
A package's validity clock starts at activation, not purchase. The
response carries both activatedAt and expiresAt, each null until the
package activates. A 30-day package bought
in January and activated in March expires in April. This trips people up when
reconciling revenue against usage: the two clocks are genuinely different.