eSIM

Is installing an eSIM the same as activating a plan?

Installation adds a digital SIM to the device; activation and the start of package validity follow the rules of the selected service.

A customer sees “installed” on the phone and “pending” in an app. Those labels can describe different observations. The device, the network and the purchase record do not share one universal state.

Which steps should the customer understand?

The provider supplies a digital SIM profile containing the mobile identity and credentials the device uses to connect. Installation adds that profile to the device. The purchased plan determines which service the customer can use.

The customer may need to enable the profile. They may also need to select it for mobile data. The customer also follows the plan’s roaming instructions.

Connecting to a covered network and using data are further outcomes. A successful checkout establishes a purchase result; it does not prove those device steps happened.

When does the package start?

The selected offer defines the event that starts the package and the validity period. Your app must show those terms before the customer decides when to install.

For a customer preparing before departure, separate the steps available at home from those requiring a covered network at the destination.

Why can the displayed states differ?

Gigs reports an unknown profile status when lifecycle information is unavailable. Your app should keep that status visible. Missing information does not establish whether installation succeeded or failed.

In Gigs’ profile lifecycle, a status response can skip stages. A Gigs disabled-profile event can arrive late if the device has lost connectivity. Show the reported state with its observation time. If either is unavailable, keep that absence visible.

In your installation journey, keep setup instructions available until the customer has verified the connection. A purchase confirmation alone cannot establish that result.

In short

  1. Installation describes the device profile.

    A profile can be present on a phone without the intended network service being in use.

  2. The offer specifies the validity rule.

    The offer defines the event that starts the package and its validity period.

  3. A missing observation is not a failed installation.

    Show unavailable status as unknown and keep observation times visible.

Put it into practice.

Continue with the documentation, guides and examples for this topic. Resources are in English.

Get an implementation brief

Build your mobile service with Bird.

Bring your markets, plan requirements and customer journey. Explore mobile connectivity with Bird and prepare your first service.

Start with one channel.
Add the others when you're ready.

A test API key is yours immediately. Production unlocks when you add a payment method and verify a sender.

Using Claude Code, Cursor, or Codex? Copy a setup prompt and your agent installs the Bird CLI and skills for you. Pick yours:

Cursor