User plan lifecycle

A user plan is one user's line: its number and its eSIM. Its status is on every GET /v1/user-plans/{userId} response. The status is worked out from the plan's numbers, which is why stopping or ending a line shows up here too.

States

Status	Meaning	Your action
INACTIVE	The plan has no line: none has been provisioned yet, the line ended on its termination date, or a failed port-in was discarded.	Create a user plan, or submit a port-in to bring a number.
PROVISIONING	A new number and eSIM are being set up with the provider.	Poll GET /v1/user-plans/{userId} until the plan is ACTIVE.
PORTING	A port-in is bringing the number in.	Follow the port-in lifecycle.
PORTING_FAILED	The last port-in for the number was refused or failed, and no other is in flight.	Read the port-in’s `failure`, correct the data and submit a new port-in for the same number, or discard it to give up on the number.
ACTIVE	The line is live. The plan also reads ACTIVE while a SIM is being replaced, while mobile data is being stopped or restored, and while the number is suspended, when no traffic flows; the number's own state says which.	Render the QR from the activation code; replace the SIM if lost.
TERMINATING	A termination is scheduled. Also reported, with no termination date, while the number is being ported out to another carrier.	None; the line stops on its termination date, or leaves once the port-out completes.
TERMINATING_WITH_DELETION	A termination is scheduled with deleteUser. On the termination date the user is deleted, and the plan with it.	None; afterwards GET /v1/user-plans/{userId} returns 404.

What to build

• Create, then wait for ACTIVE. POST /v1/user-plans returns PROVISIONING; a port-in, submitted separately, moves the plan to PORTING. Poll GET /v1/user-plans/{userId} until it is ACTIVE.
• Read the activation code once ACTIVE. It is the LPA string on the number; render your own QR. See the eSIM install flow.
• Read TERMINATING with terminationScheduledAt. When it is set, the plan is ending on that date. When it is null, the number is being ported out to another carrier. Suspending a number doesn't end its plan, so a plan whose number is suspended reads ACTIVE until its end is booked.
• End a plan with the API. See End a plan.

The UserPlanCreated and UserPlanActive webhooks carry the status too, so you can be notified of a plan going ACTIVE instead of polling.

Related

• Provision a line
• Number and eSIM lifecycle