Skip to main content
Les factures natives utilisent les mêmes chemins /invoices que les factures legacy, mais ont un format de requête et un cycle de vie différents. Ce guide fait correspondre les champs et actions que vous devez modifier lors de la migration d’une intégration.
Les chemins partagés renvoient vers les factures natives à partir de Api-Version-Date: 2026-10-24. Les exemples natifs ci-dessous utilisent Api-Version-Date: 2026-11-02-1, avec les noms de champs de variante actuels et les règles de verrouillage du client. Envoyez cet en-tête dans chaque requête native. Conservez les appels legacy sur une version publiée antérieure, comme 2026-10-15-1. Versions de l’API explique comment les en-têtes remplacent les versions épinglées aux identifiants.

Ce qui change

L’API native ne liste ni ne récupère les factures legacy inv_. Continuez à lire les factures legacy existantes avec la version antérieure de l’API. Créer une facture native crée une facture distincte. Cela ne convertit ni ne règle une facture legacy.

Avant de migrer

Vérifiez ces différences avant de migrer un flux. Conservez-le sur l’API legacy s’il nécessite une fonctionnalité que l’API native ne fournit pas.

Faire correspondre la requête de création

Une création legacy envoie un plan et, éventuellement, des libellés qui répartissent son prix. Une création native envoie un item pour chaque variante facturée. Ces exemples définissent un prix total des items de 19,99 USD. La variante native existante représente les frais de mise en place de 15 USD. Les frais de service de 4,99 USD sont des frais ponctuels personnalisés sans produit. Les deux API acceptent des prix en unités monétaires. Utilisez 4.99 pour 4,99 USD. Envoyer 499 facture 499 USD.
La requête native crée un brouillon. Envoyez-le avec POST /invoices/{id}/send pour l’émettre et l’envoyer par e-mail. member_id identifie un client (mber_), pas un abonnement (mem_). Pour les versions natives antérieures à 2026-10-27-2, utilisez plan_id, plan et plan_type au lieu de variant_id, variant et billing_type. Les lignes de la réponse utilisent aussi plan_id sur ces anciennes versions.

Garder les montants émis verrouillés

PATCH /invoices/{id} modifie les items et les informations de facturation d’un brouillon. Envoyer items remplace toute la liste en utilisant les prix actuels des variantes. L’omettre conserve les items et les prix enregistrés.
  • Annulez un envoi planifié avant de modifier les items ou les informations de facturation.
  • À partir de 2026-11-02-1, vous ne pouvez ni remplacer ni supprimer le client attribué à un brouillon. Un brouillon sans client peut toujours en recevoir un. Annulez le brouillon avant de créer une nouvelle facture pour quelqu’un d’autre.
  • email_address et customer_name ne peuvent être saisis qu’à la création.
  • Les montants et items émis sont verrouillés. Une mise à jour ne contenant que memo et/ou recipient_emails est autorisée sur les factures draft, open et uncollectible, y compris un brouillon planifié.

Émettre, envoyer et débiter

Une création legacy choisit le mode d’encaissement avec collection_method. Les factures natives utilisent des appels distincts après la création du brouillon :
  1. Émettez-la avec POST /invoices/{id}/issue pour calculer la taxe finale et l’ouvrir au paiement sans envoyer l’e-mail initial de facture.
  2. Ou envoyez-la avec POST /invoices/{id}/send. Cela émet le brouillon. L’e-mail est envoyé aux destinataires, sauf si un moyen enregistré est débité immédiatement. Envoyer une facture open la renvoie par e-mail. send_at planifie l’envoi d’un brouillon. POST /invoices/{id}/unschedule annule cette planification.
  3. Débitez un moyen enregistré en définissant payment_method_id sur le brouillon. Pour un total positif, l’émission ou l’envoi débite à une date charge_at future, sinon à une date due_at future, sinon immédiatement. charge_at doit être dans le futur et ne peut pas précéder send_at.
Envoyer un brouillon débité immédiatement ignore l’e-mail initial de facture. Envoyer avec un débit ultérieur l’envoie par e-mail dès maintenant. Un débit automatique échoué peut déclencher un e-mail avec un lien de paiement, même si vous avez utilisé Issue Invoice. Débiter un moyen de paiement enregistré explique le flux. Une réponse open ne confirme pas le paiement. Attendez payment.succeeded avant de traiter la commande. Pour débiter ou relancer une facture ouverte, utilisez Charge Invoice. L’émettre ou l’envoyer à nouveau ne déclenche pas de nouveau débit. Pour une variante récurrente, collection_method sur Issue Invoice ou Send Invoice contrôle les renouvellements. charge_automatically encaisse automatiquement les paiements futurs. send_invoice crée et envoie par e-mail une nouvelle facture à chaque période. Cela ne remplace pas payment_method_id pour encaisser la première facture. Consultez Facturer un abonnement.

Faire correspondre la réponse

Pour télécharger un PDF, appelez POST /invoices/{id}/generate_pdf afin d’obtenir un lien de courte durée.

Ouvrir le checkout de la facture

checkout_link contient l’ID de la facture et un jeton signé séparés par un .. Passez la valeur entière en tant que link à POST /checkout_sessions pour ouvrir une session pour cette facture. Pour une URL destinée au client, suivez Construire l’URL du checkout hébergé. Le champ n’est présent que tant que le checkout est disponible : la facture doit être open. Les acheteurs professionnels et les adhésions annulées ne peuvent pas utiliser ce checkout. Votre clé nécessite payment:charge, ou invoice:create/invoice:update lorsque la facture n’a pas de moyen de paiement enregistré. Il vaut null sur une facture brouillon, payée, annulée ou irrécouvrable, ainsi que pour les acheteurs professionnels.

Faire correspondre les statuts

Les factures natives peuvent aussi renvoyer authorized, pending ou unresolved. Ne considérez pas tout statut hors de l’enum legacy comme payé ou échoué. Statuts et cycle de vie les explique.

Faire correspondre les endpoints

Faire correspondre les webhooks

Les factures natives envoient des événements de paiement pour leur ID pay_. Les événements invoice.* décrivent les factures legacy. Les événements de paiement couvrent aussi les paiements sans lien avec les factures. Faites correspondre l’ID de paiement de l’événement aux ID de factures natives que vous stockez. Webhooks montre comment traiter la commande à partir de payment.succeeded.

Autorisations

member:basic:read expose les noms des clients et les ID de membre/d’adhésion. member:email:read expose email_address et recipient_emails. Les champs de moyen de paiement et d’adresse nécessitent payment:basic:read.

Liste de contrôle de la migration

  1. Consultez Avant de migrer pour les flux qui doivent rester sur l’API legacy.
  2. Épinglez les appels natifs à une version publiée correspondant à leurs noms de champs, comme 2026-11-02-1 pour ces exemples.
  3. Construisez items à partir de variantes éligibles, en vérifiant les quantités, les prix, la devise et les exigences de produit.
  4. Remplacez la création legacy en un seul appel par une création, suivie d’une émission ou d’un envoi. Choisissez les débits de moyens enregistrés pour la première facture et un mode d’encaissement pour les renouvellements.
  5. Faites correspondre les dates d’échéance, les envois planifiés et les frais acheteur selon leur comportement, pas seulement leurs noms de champs.
  6. Gardez distincts les ID natifs pay_ et les ID legacy inv_. Conservez les lectures legacy sur la version antérieure.
  7. Lisez les montants dans les objets monétaires et ouvrez le checkout avec le checkout_link signé.
  8. Gérez overdue et les statuts de paiement supplémentaires.
  9. Traitez la commande à partir de payment.succeeded pour l’ID de paiement de la facture.
  10. Accordez les autorisations utilisées par votre flux, y compris celles pour les variantes/produits en ligne et la lecture des clients.

Étapes suivantes

Guide des factures

Créez, émettez, envoyez et encaissez des factures natives.

Référence API des factures

Chaque endpoint et champ des factures natives.

API de factures legacy

Les endpoints appelés par votre intégration actuelle.

Versions de l'API

Fonctionnement de Api-Version-Date et de l’épinglage de version.