Manage recurring eSIM packages
A recurring package purchases data on a billing schedule. Availability depends on the selected offer and eSIM. Check the published recurring terms before offering renewal to your customers; a one-time package does not establish renewal support or included calls and SMS.
This guide covers enrollment, renewal, and cancellation. The eSIM API does not provide an operation to switch an active subscription to another plan or transfer a mobile number.
1. Review the recurring terms
Get the offer's recurring terms. Review its price, currency, cadence, and delivery mode. calendar_month follows calendar months; fixed_days uses the stated number of 24-hour days. The organization wallet funds purchases; the assigned subscriber is the person using the service.
Check whether the package covers the paid interval (exact_period) or renews by buying a standard top-up (recurring_top_up). With recurring top-ups, package activation and expiry follow the package terms and can differ from billing boundaries. Make these terms visible before the customer accepts.
2. Assign the subscriber
Create a subscriber from a contact in your workspace, then assign the eSIM. Creating the subscriber requires Contacts read permission as well as eSIM write permission. The subscriber association prevents deletion of that contact and cannot currently be removed, including after the eSIM ends.
Assignment does not grant workspace access or permission to read installation credentials. Complete any required identification checks through your own authorized process.
3. Enroll and verify delivery
For an existing assigned eSIM, create a recurring subscription with the eSIM, offer, accepted revisions, and accepted price. Use an Idempotency-Key and retain it for retries. 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 with automatic renewal, use the recurring option from checkout terms and submit it through Create an order.
4. Monitor renewal
Open Subscriptions to inspect accepted terms, status, and the next renewal. In the API, check 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 rather than buying another subscription to work around it.
5. Stop future renewal
Cancel the subscription, then read it again to confirm the cancellation state and effective date. A period already committed remains payable. Delivered packages retain their own validity, and the installed profile is preserved.
Removing the profile from the phone does not cancel renewal. Releasing an eSIM is a separate irreversible action that forfeits remaining data; use it only when you intend to end use of the profile.
Troubleshooting
Adding wallet funds does not automatically restart a subscription whose renewal has stopped. Inspect stop_reason and confirm the previous service has ended before accepting a new enrollment. For a pending initial purchase, use the purchase recovery steps.
A failed paid delivery and its credit have separate outcomes. Check period history for order_status and refund_transaction_id; a canceled renewal alone does not establish that a refund was issued.
Verify the first renewal
Use an available offer and an authorized live purchase to check the complete flow: accepted terms, first package delivery, the next funded period, and cancellation. A test-mode eSIM does not establish live recurring-service availability.
Confirm that your customer can find the allowance, next renewal, cancellation date, and support contact. Test the advertised data service on a compatible device. Verify calls and SMS separately if the selected offer includes them.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic.