Allo

Changer le palier d'une eSIM

Fait passer une eSIM à un autre palier de données. Une montée de palier est débitée tout de suite et ajoute les données en plus en une minute environ. Une…

PUT/v2/api/partner/esims/{id}/tier

Fait passer une eSIM à un autre palier de données. Une montée de palier est débitée tout de suite et ajoute les données en plus en une minute environ. Une baisse de palier s'applique à la fin de la période déjà payée.

Requête

  • tier est requis : un tiers[].code renvoyé par Obtenir l'offre eSIM, par exemple ESIM_20GB. ESIM est le palier sans données mobiles. Un code inconnu échoue avec INVALID_ESIM_TIER.
  • L'eSIM doit être ACTIVE. Tant qu'elle est en cours de provisionnement, la requête échoue avec ESIM_NOT_READY.

Réponse

statusSignification
ACTIVEL'eSIM est déjà sur ce palier. Rien n'est débité.
PENDINGMontée de palier. Allo la débite tout de suite, et les données en plus sont ajoutées en une minute environ, une fois le paiement confirmé.
SCHEDULEDBaisse de palier. L'eSIM garde son palier actuel jusqu'à effective_at, la fin de la période déjà payée, puis passe au nouveau palier. Rien n'est remboursé.

effective_at vaut null sauf si status vaut SCHEDULED. Obtenir une eSIM renvoie le tier actuel, la baisse prévue dans scheduled_tier et scheduled_tier_at, et le quota du mois dans data.allowance_mb.

Une montée de palier relève le quota : partner.esim.data_low et partner.esim.data_exhausted peuvent alors être envoyés à nouveau quand l'eSIM approche du nouveau quota.

Facturation

  • Une montée de palier est facturée sur l'abonnement que vous payez pour le compte, au prorata du reste de la période de facturation en cours, avec votre remise partenaire appliquée. L'abonnement se renouvelle ensuite au prix du nouveau palier.
  • Allo prélève d'abord votre crédit prépayé, puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
  • Si votre crédit prépayé ne couvre pas la montée de palier et qu'aucune carte n'est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT.
  • Une carte refusée, ou une carte qui exige 3D Secure, échoue avec 402 ESIM_PAYMENT_FAILED. Une validation 3D Secure est impossible via l'API : Allo annule la tentative et rien ne reste en attente. Réessayez avec une autre carte, mise à jour dans le portail partenaire, ou après avoir rechargé votre crédit prépayé.
  • Une baisse de palier ne débite rien et ne rembourse rien.

Nouvelles tentatives

Envoyez un en-tête Idempotency-Key (8 à 100 lettres, chiffres, - ou _, par exemple un UUID) et réutilisez-le pour réessayer le même changement. Une nouvelle tentative avec la même clé ne vous débite pas deux fois. Une clé dans un autre format échoue avec INVALID_IDEMPOTENCY_KEY.

Erreurs propres à l'eSIM

CodeSignification
ESIM_NOT_READYL'eSIM est encore en cours de provisionnement. Attendez partner.esim.ready, puis réessayez.
ESIM_NOT_ACTIVEL'eSIM a été supprimée, ou le numéro a une commande d'eSIM plus récente. Seule la dernière eSIM du numéro peut être modifiée : utilisez son id, ou commandez une nouvelle eSIM avec Commander une eSIM.
ESIM_TIER_CHANGE_CONFLICTUne baisse de palier est déjà prévue pour cette eSIM. Elle ne peut pas être remplacée avant de s'appliquer, à scheduled_tier_at.
ESIM_SUBSCRIPTION_CONFLICTL'abonnement que vous payez pour le compte ne peut pas être débité pour des eSIM pour le moment. Si l'erreur indique retryable: true, réessayez dans quelques minutes.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

idstringrequis

The eSIM id returned by Order eSIM (eso-*).

En-têtes

Idempotency-Keystring

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Corps

tierstringrequis

A tier code from Get eSIM offer. ESIM is the tier with no mobile data.

Réponses

200Tier change accepted
dataobject
4 champs
esim_idstring

The eSIM id (eso-*).

tierstring

The tier you asked for.

statusenum<string>

ACTIVE: the eSIM is already on this tier, nothing is charged. PENDING: upgrade charged, the extra data is added once the payment is confirmed. SCHEDULED: downgrade, it applies at effective_at.

ACTIVEPENDINGSCHEDULED

effective_atstring<date-time> | null

When a scheduled downgrade applies: the end of the period already paid. null unless status is SCHEDULED.

400Validation error: MISSING_FIELD (tier), INVALID_ESIM_TIER or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure, and the attempt was cancelled: retry with another payment method or after topping up your credit.
errorobject
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), or the account the eSIM belongs to is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
errorobject
409The eSIM is still provisioning (ESIM_NOT_READY), was deleted or is not the number's latest eSIM (ESIM_NOT_ACTIVE), already has a downgrade scheduled (ESIM_TIER_CHANGE_CONFLICT), or the subscription you pay for the account cannot be charged for eSIMs right now (ESIM_SUBSCRIPTION_CONFLICT).
errorobject
429
500The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The message gives the reason.
errorobject