Allo

Revoke eSIM

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

CodeWhat it means
PARTNER_ESIM_NOT_REVOCABLEThe 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_FAILEDThe 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_FOUNDNo 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.

401
403The 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.
errorobject
429