SIMs lifecycle

A SIM in Helium MVNE is a first-class resource with its own state machine. The carrier dictates the legal transitions; the platform enforces them and emits events.

State diagram

Ordering a SIM

POST /v1/sims
  subscriber_id, ship_to_address_id?, type=physical|esim

Physical SIMs trigger a fulfillment event; eSIMs return an activation code (LPA string) immediately.

Activation

POST /v1/sims/{id}/activate
  subscription_id, msisdn?  # omit msisdn to get a new one

Activation is async. The call returns 202 Accepted and moves the SIM to pending_activation. The carrier calls us back with either activation_success or activation_failed; we emit the matching event.

Suspension, swap, deactivation

All three accept an optional reason string that flows through to the carrier and the sim.* events.

Sandbox testing

In sandbox, use the dashboard's Sandbox → Triggers panel to fast-forward a SIM through the async transitions without waiting on the simulated carrier's delay — see Testing in sandbox.