Connectivity Lifecycle

SIM swap

Replace the SIM associated with an existing subscription while keeping the subscription active.

This makes the flow ideal for:

  • damaged SIM replacement
  • lost SIM replacement
  • switching from physical SIM to eSIM
  • moving service to another device

Best for: Use this flow when you want to replace the current SIM for an existing subscription without creating a brand new subscription.

What you will do


Replacement flow

SIM swap, step by step

Follow the lifecycle used to replace the SIM on an existing subscription while keeping the subscription itself intact.

01
Identify active subscription
Subscription lookup / customer action
Result
Target subscription identified

Identify the active subscription that requires a SIM replacement before starting the swap flow.

↓
02
Create SIM swap order
POST /orders
Result
201 Order Created

Create a SIM swap order for the existing subscription so Connect can prepare the replacement SIM while preserving the subscription lifecycle.

↓
03
Replacement SIM ready
Webhook delivery
Result
SIM profile ready for installation

Once the replacement SIM is prepared, Connect emits the event that indicates the new SIM profile is ready to be installed or delivered.

Events
subscription.sim_profile_ready_for_installation
↓
04
Activate replacement SIM
Customer installation / delivery flow
Result
New SIM in use

Deliver the replacement SIM to the customer and complete installation or activation on the target device.

↓
05
Swap completed
Webhook delivery
Result
Subscription continues with new SIM

Connect confirms the swap completion and the subscription continues operating with the replacement SIM.

Events
order.completedsubscription.active