Revokes an eSIM right away: it stops working on its phone for good. The number stays on the account, keeps its history and rings the Allo apps instead. The…
POST/v2/api/partner/esims/{id}/revoke
Revokes an eSIM right away: it stops working on its phone for good, for example when the phone is lost or its holder leaves. The response returns the eSIM with status REVOKED.
What happens to the number
The number stays on the account, with the same owner and its call and message history.
Calls to the number ring the Allo apps instead of the eSIM.
The eSIM's data tier ends now and is no longer billed.
A revoked eSIM cannot be reactivated. To put the number on a phone again, order a new eSIM for it. The new order charges the setup fee.
Remove member revokes the member's eSIMs for you, so you do not need to call this endpoint first.
Idempotency
Revoking an eSIM that is already REVOKED returns it unchanged. An eSIM replaced by a later eSIM on the same number also reads REVOKED, and revoking it never touches the new one.
Errors
Code
What it means
PARTNER_ESIM_NOT_REVOCABLE
The eSIM is not live: it is still PROVISIONING, it FAILED, or it is being moved between the network and the eSIM (409). Only an ACTIVE eSIM can be revoked. Check it with Get eSIM.
PARTNER_ESIM_MOVE_FAILED
The eSIM failed to move between the network and the eSIM (409), so it cannot be revoked until it is checked. Contact Allo support. Nothing was changed.
PARTNER_ESIM_NOT_FOUND
No eSIM with this id was ordered on an account your API key created (404).
Authorization
Authorizationstring · headerrequired
Api-Key ak_live_…
Path parameters
idstringrequired
The eSIM id returned by Order eSIM (eso-*).
Responses
200The revoked eSIM, with status REVOKED
dataobject
8 fields
idstring
The eSIM id (eso-*).
account_idstring
The account the eSIM was ordered for.
partner_client_refstring | null
Your own reference, set when the account was created.
phone_numberstring
The number the eSIM carries.
tierstring
The tier code that was ordered.
statusenum<string>
PROVISIONING: ordered, not ready yet. ACTIVE: ready, calls to the number ring the eSIM. FAILED: the order did not complete, see failure_code. REVOKED: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.
PROVISIONINGACTIVEFAILEDREVOKED
failure_codestring | null
Why the order failed. Set only when status is FAILED.
created_atstring<date-time>
When the eSIM was ordered.
401403The API key lacks the PARTNER scope.
errorobject
404No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).
errorobject
409The eSIM is not live: it is still provisioning, it failed, or it is being moved between the network and the eSIM (PARTNER_ESIM_NOT_REVOCABLE). Only an ACTIVE eSIM can be revoked.