API Mobile V2 — Le détail d'une souscription sépare la commande d'origine (`order`) de l'état du service (`service`)

🚧
Action requise : migration à prévoir dès maintenant
La réponse de GET /mobile/subscriptions/{subscription_id} change de forme : les informations de la commande d'origine sont regroupées sous une clé order, et service expose désormais le produit en vigueur sur la ligne.
La nouvelle forme s'obtient dès aujourd'hui avec le paramètre legacy=false. L'ancienne forme est dépréciée : elle sera retirée de cette route, sans changement de version de l'API, et la nouvelle forme deviendra alors la seule renvoyée, que le paramètre legacy soit passé ou non. Ne démarrez pas de nouvelle intégration sur l'ancienne forme, et planifiez la migration des intégrations existantes.

Endpoint impacté

GET /api/v2-beta/mobile/subscriptions/{subscription_id}

Pourquoi ce changement ?

Une souscription porte deux familles d'informations dont le cycle de vie est différent :

la commande d'origine : le produit commandé, le quota commandé, la SIM commandée, la portabilité demandée, le client, la référence externe. Ces informations sont figées au moment de la commande.
le service : l'état en vigueur de la ligne. Il évolue au fil de la vie de la ligne : changement de forfait, changement de SIM, extension de data, suspension, résiliation.

La nouvelle forme rend ce cycle de vie explicite : order n'est jamais altéré par une modification du service, seule la partie service est mise à jour. Pour connaître l'offre réellement en vigueur sur une ligne, lisez service.

Ce qui change concrètement

Information	Ancienne forme (`legacy=true`)	Nouvelle forme (`legacy=false`)
Produit, variante, quota, SIM, portabilité, client, référence, statut et dates de la commande	à la racine	sous `order`, valeurs inchangées
Date d'activation `activated_at`	à la racine et dans `service`	uniquement dans `service`
Produit, variante et SKU en vigueur sur la ligne	❌ absents	✅ `service.product_id`, `service.variant_id`, `service.sku`

Le produit en vigueur dans `service`

service.product_id et service.variant_id désignent la version de l'offre actuellement appliquée à la ligne. Ils sont égaux à order.product_id et order.variant_id tant qu'aucun changement de forfait n'a eu lieu, puis divergent.

service.sku est la référence commerciale de la variante en vigueur (ou du produit lorsqu'il n'a pas de variante). Comme indiqué dans l'annonce du 22 septembre, le sku est le repère stable pour identifier une offre : c'est lui qu'il faut comparer, pas les identifiants techniques.

Exemple

Avant (legacy absent ou true)

{
  "subscription_id": "0c14083f-6bba-4895-8302-c464228a8cfe",
  "product_id": "b1722721-9b46-4f12-8f11-fd16f4b87d35",
  "variant_id": "6a784265-2d1c-445d-a256-aca516b5c2fc",
  "created_at": "2026-09-03T09:12:41Z",
  "customer": { "name": "ACME SAS", "company_number": "12345678900012" },
  "quota_label": "1 Go FR | 1 Go EU",
  "data_quota_bytes_per_mobile_area": { "...": "..." },
  "external_reference": "CMD-2026-00042",
  "portability": null,
  "sim_card": "esim",
  "status": "active",
  "updated_at": "2026-09-05T14:27:18Z",
  "activated_at": "2026-09-05T14:27:18Z",
  "service": {
    "msisdn": "+33698453172",
    "quota_label": "100 Go FR | 100 Go EU",
    "data_quota_bytes_per_mobile_area": { "...": "..." },
    "...": "..."
  }
}

Après (legacy=false)

{
  "subscription_id": "0c14083f-6bba-4895-8302-c464228a8cfe",
  "order": {
    "product_id": "b1722721-9b46-4f12-8f11-fd16f4b87d35",
    "variant_id": "6a784265-2d1c-445d-a256-aca516b5c2fc",
    "created_at": "2026-09-03T09:12:41Z",
    "customer": { "name": "ACME SAS", "company_number": "12345678900012" },
    "quota_label": "1 Go FR | 1 Go EU",
    "data_quota_bytes_per_mobile_area": { "...": "..." },
    "external_reference": "CMD-2026-00042",
    "portability": null,
    "sim_card": "esim",
    "status": "active",
    "updated_at": "2026-09-05T14:27:18Z"
  },
  "service": {
    "product_id": "10eceda5-173c-411b-89f9-829075c21fee",
    "variant_id": "f3e88581-28b4-4daa-abb4-698911b69121",
    "sku": "MOB-PRO-100GO",
    "msisdn": "+33698453172",
    "quota_label": "100 Go FR | 100 Go EU",
    "data_quota_bytes_per_mobile_area": { "...": "..." },
    "...": "..."
  }
}

Dans cet exemple, la ligne a été commandée sur une offre 1 Go puis est passée sur une offre 100 Go : order décrit toujours la commande 1 Go, service décrit l'offre 100 Go en vigueur.

Comment migrer

Ajoutez ?legacy=false à vos appels GET /mobile/subscriptions/{subscription_id}.
Lisez les champs de la commande sous order au lieu de la racine.
Lisez activated_at dans service.
Si votre intégration affiche ou facture « l'offre de la ligne », basez-vous sur service.product_id, service.variant_id et service.sku, pas sur order.

Le paramètre legacy=false est disponible dès maintenant. Tant que vous ne le passez pas, la réponse garde son ancienne forme, le temps de votre migration. Nous annoncerons la date de retrait de l'ancienne forme dans ce changelog ; prenez les devants, les intégrations non migrées à cette date seront impactées.

Besoin d'aide ?

Votre Customer Success Manager est disponible pour vérifier votre intégration avec vous.

Action requise : migration à prévoir dès maintenant