Manage recurring eSIM packages

Use a recurring subscription to purchase data packages on a billing schedule. You need permission to purchase eSIM service, organization wallet funds, and a subscriber for the person using the eSIM. Availability depends on the selected offer and profile.

This guide covers new purchases and enrollment on an existing eSIM. The eSIM API does not provide an operation to switch an active subscription to another plan.

1. Review the recurring terms

For a new eSIM, get checkout options. Offer automatic renewal when recurrence.available is true and use its quote for the accepted terms. If unavailable, inspect unavailable_reason and offer a supported purchase option.

For an existing eSIM, list compatible offers with recurring_only=true, then get the selected offer's recurring terms. Enrollment checks compatibility again before accepting the purchase.

Show the recurring price, published currency, cadence, and delivery mode before acceptance. The quote is before tax; period history records the charged total and tax. calendar_month follows calendar months; fixed_days uses the stated number of 24-hour days. The organization wallet pays for the service; the subscriber has no separate wallet.

Check whether the package covers the paid interval (exact_period) or each renewal buys a standard package (recurring_top_up). With recurring top-ups, activation and expiry follow the package terms and can differ from billing boundaries. Do not promise uninterrupted data solely because renewal is scheduled.

2. Assign the subscriber

In the dashboard, open the profile from eSIMs, open More eSIM actions, select Assign person, choose the contact, and confirm Assign person. You cannot change the assigned person later.

With the API, create a subscriber using the contact_id of a contact in your workspace. This requires email_marketing:read for Contacts and esim:write. The response returns the existing subscriber when the contact already has one.

Creating the association prevents contact deletion, including after the eSIM ends. Subscriber associations cannot currently be removed, detached, or anonymized. Decide whether that retention fits your customer process before creating one.

For an existing profile, assign the eSIM using subscriber_id. Repeating the same assignment returns the existing record; assigning a different person returns 409. For a new profile, include subscriber_id in the purchase so assignment completes with delivery.

Assignment does not grant workspace access or permission to read installation credentials. Handle identification collection separately using the offer requirements and the integration guide.

3. Enroll and verify delivery

For an existing assigned eSIM in the dashboard, open Automatic renewal and select Set up renewal. Choose a Package, select Check recurring price, and review the price, cadence, and package delivery terms. Select Buy first package and renew to purchase the first period and enable renewal.

For a new eSIM through the API, create an order with the selected offer_id, workspace subscriber_id, and these accepted checkout terms:

• Set offer_revision to recurrence.quote.offer_revision.
• Set recurrence.recurrence_revision to recurrence.quote.recurrence_revision.
• Set recurrence.accepted_price to the complete recurrence.quote.price object.

Send an Idempotency-Key; omit esim_id and expected_price for this purchase. Save the order ID and its recurring_subscription_id. The first billing period starts when payment is funded. Follow the order until it completes or fails, using the purchase recovery steps if needed.

For an existing assigned eSIM, create a recurring subscription with esim_id, offer_id, the offer's revision as offer_revision, and the recurring terms' revision as recurrence_revision. Send the recurring terms' complete price as accepted_price. An Idempotency-Key is required; reuse it with the same request to recover enrollment. Enrollment purchases the first period immediately; it does not wait for an existing package to run out.

Get the subscription and list its periods. Confirm payment and package delivery separately. For a new eSIM, deliver installation details after its order completes.

4. Monitor renewal

Open Subscriptions to inspect accepted terms, status, and the next renewal. In the API, read next_renewal_at, stop_reason, and period history. A changed published price requires new acceptance; an unfunded renewal stops future purchases.

If status is needs_attention, inspect the latest period and associated order. An unresolved delivery can remain payable and blocks a replacement enrollment. Contact support with those references before purchasing a replacement.

5. Stop future renewal

In the eSIM's Automatic renewal section, select Cancel renewal. Review the current paid period end, then confirm Cancel renewal in the dialog. Check the updated subscription for its cancellation date.

With the API, cancel the subscription, then read it again. Check cancel_at_period_end, cancellation_effective_at, and next_renewal_at to confirm when renewal ends. A period already committed remains payable. Delivered packages keep their own validity, and the installed profile is preserved.

Removing the profile from the phone does not cancel renewal. Releasing an eSIM permanently retires it, forfeits remaining data, and does not refund it. Use service actions when you intend to change connectivity as well as renewal.

Troubleshooting

Adding wallet funds does not automatically restart a stopped subscription. Check stop_reason and the previous service's final state before accepting a new enrollment. A failed paid delivery and its credit have separate outcomes: inspect order_status and refund_transaction_id in period history.

Verify the customer journey

Confirm that the customer can find the purchased allowance, package expiry, next renewal, cancellation date, and support contact. Verify the first package's delivery and test mobile data on a compatible device. Check a subsequent period's payment and delivery separately from its scheduled renewal date.

Next steps

• Read balances and buy a one-time top-up.
• Prepare device installation.
• Investigate payment or delivery issues.