Passer au contenu principal
Lorsque vous devez appliquer une même modification à plusieurs abonnements — par exemple ajouter un nouveau produit à tous les clients —, vous avez plusieurs options selon votre cas d’usage et vos exigences.

​
Vue d’ensemble des méthodes

MéthodeIdéale pourAvantagesInconvénients
Mise à jour complète de l’abonnementMises à jour en masse simples sans facturation au prorataVersionnement, pas de facture de transition, conserve le cycle de facturation—
Créer une transition d’abonnementContrôle total avec versionnement et options de facturationHistorique des versions, configuration flexibleMise en place avancée
Mise à jour incrémentale (dépréciée)Cas d’usage héritésSimplePas de versionnement, non pérenne

​
Mise à jour complète de l’abonnement

Recommandée pour la plupart des scénarios de mise à jour en masse. Le point de terminaison PUT /v2/subscriptions/:id effectue une transition immédiate tout en conservant le cycle de facturation et en supprimant la facture de transition. Cela signifie qu’aucune facture au prorata n’est générée.

Exemple 💡

Vous souhaitez ajouter un nouveau produit « Support » à tous les abonnements actifs. Avec cette méthode, le produit est ajouté immédiatement sans générer de frais au prorata, et les clients continuent sur leur cycle de facturation existant.

​
Comment cela fonctionne

  1. Récupérez l’abonnement via GET /v2/subscriptions/:id pour obtenir sa configuration actuelle
  2. Ajoutez le nouveau produit aux phases de l’abonnement
  3. Appelez PUT /v2/subscriptions/:id avec la charge utile complète de l’abonnement mis à jour
La structure de la charge utile correspond à la réponse de GET /v2/subscriptions/:id, ce qui vous permet de récupérer un abonnement, de le modifier et de le mettre à jour en utilisant la même structure. 
curl -X PUT "https://api.hyperline.co/v2/subscriptions/{subscription_id}" \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phases": [
      {
        "id": "phase_xxx",
        "products": [
          ...
          {
            "product_id": "prod_new_product_id",
            "price": {
              "type": "flat_fee",
              "amount": 1000,
              "interval": "month"
            }
          }
        ],
        ...
      }
    ],
    ... // Existing subscription payload
  }'

​
Quand l’utiliser

  • Ajouter un produit à plusieurs abonnements sans facturation au prorata
  • Effectuer des modifications de configuration simples sur plusieurs abonnements
  • Lorsque vous souhaitez un historique des versions avec une configuration minimale

​
Créer une transition d’abonnement

Utilisez le point de terminaison de transition lorsque vous avez besoin d’un contrôle total sur le processus de mise à jour, y compris les options de facturation.

​
Option A : transmettre la configuration complète de l’abonnement

Appelez POST /v2/subscriptions/transitions avec la configuration de l’abonnement source et l’abonnement cible incluant le nouveau produit. 
curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_subscription_id": "sub_xxx",
    "application_schedule": "immediately",
    "billing_cycle_transition_method": "keep_current_billing_cycle",
    "calculation_method": "do_not_charge",
    "target_subscription": {
      "phases": [
        {
          "products": [
            ...
          ],
          ...
        }
      ],
      ... // Existing subscription payload
    }
  }'

​
Option B : transition vers un modèle/plan mis à jour

Si l’abonnement a été créé à partir d’un modèle ou d’un plan et n’a pas été personnalisé depuis, et que vous avez déjà mis à jour ce modèle/plan avec le nouveau produit, vous pouvez faire transiter l’abonnement vers le modèle mis à jour.

Exemple 💡

Vous avez 100 clients sur le modèle « Pro Plan ». Vous ajoutez un nouveau produit « Analytics » au modèle Pro Plan. Au lieu de spécifier la configuration complète de l’abonnement pour chaque client, vous faites transiter chaque abonnement vers le modèle Pro Plan mis à jour.
curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_subscription_id": "sub_xxx",
    "application_schedule": "immediately",
    "billing_cycle_transition_method": "keep_current_billing_cycle",
    "calculation_method": "do_not_charge",
    "target_subscription": {
      "subscription_template_id": "template_xxx"
    }
  }'
Cette approche est efficace lorsque de nombreux abonnements partagent le même modèle, car vous n’avez besoin de passer que l’identifiant du modèle plutôt que la configuration complète de l’abonnement.

​
Options de transition

ParamètreDescription
application_scheduleQuand appliquer : immediately ou scheduled (avec transition_date)
billing_cycle_transition_methodkeep_current_billing_cycle pour conserver les dates de facturation actuelles, align_to_new_billing_cycle pour réinitialiser
calculation_methoddo_not_charge pour ignorer la facture de transition, pro_rata pour générer une facture au prorata

​
Mise à jour incrémentale (dépréciée)

Le point de terminaison POST /v1/subscriptions/:id/update-many est déprécié. Il ne gère pas le versionnement et n’est pas pérenne. Utilisez plutôt l’une des méthodes ci-dessus.
Ce point de terminaison permet de mettre à jour plusieurs aspects d’un abonnement en un seul appel, mais ne conserve pas l’historique des versions.

​
Scripter les mises à jour en masse

Pour mettre à jour plusieurs abonnements, écrivez un script qui :
  1. Liste tous les abonnements cibles via GET /v2/subscriptions avec les filtres appropriés
  2. Pour chaque abonnement, applique la mise à jour avec la méthode de votre choix
  3. Gère les erreurs et les nouvelles tentatives au besoin
Utilisez la pagination et la limitation de débit dans votre script. Consultez la documentation sur la limitation de débit pour plus de détails.
Quelque chose reste flou ? N’hésitez pas à contacter notre équipe via le chat dans l’application si vous avez besoin d’une assistance supplémentaire.