Can I reuse an esimReference across multiple plans?

Yes. esimReference is the physical eSIM profile. You can attach multiple plans to it over time (top-ups). profileReference is the per-plan attachment.

The short answer

Yes.

esimReference

represents the physical eSIM profile on the device. You attach plans to it over its lifetime. Each plan attachment is a separate

profileReference

The mental model

Try it yourself

Free sandbox. Real Tier-1 carriers. 60 seconds from signup to credentials.

Get started →

esimReference
= the SIM card slot. One per device.
profileReference
= a plan attached to that slot. Many per
```
esimReference
```
over time.
iccid
= the GSMA identifier. One per
```
esimReference
```
, never changes.

Typical lifecycle

1. Create eSIM         -> returns esimReference + iccid
2. Customer installs   -> esim.activated webhook
3. Attach plan A       -> returns profileReference_A
4. Plan A expires      -> profile.expired webhook
5. Attach plan B       -> returns profileReference_B (same esimReference)
6. Customer top-up...  -> repeat

When you should NOT reuse

After 12 months of no activity. The carrier reclaims the slot.
If the customer formally cancels and you call
```
DELETE /esims/{ref}
```
.
For testing: always create a fresh sandbox eSIM per test run.

See the identifiers guide for the full breakdown.

Was this helpful?

Related help