/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. Utilisez4.99 pour 4,99 USD. Envoyer 499 facture 499 USD.
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_addressetcustomer_namene peuvent être saisis qu’à la création.- Les montants et items émis sont verrouillés. Une mise à jour ne contenant que
memoet/ourecipient_emailsest autorisée sur les facturesdraft,openetuncollectible, y compris un brouillon planifié.
Émettre, envoyer et débiter
Une création legacy choisit le mode d’encaissement aveccollection_method. Les factures natives utilisent des appels distincts après la création du brouillon :
- Émettez-la avec
POST /invoices/{id}/issuepour calculer la taxe finale et l’ouvrir au paiement sans envoyer l’e-mail initial de facture. - 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 factureopenla renvoie par e-mail.send_atplanifie l’envoi d’un brouillon.POST /invoices/{id}/unscheduleannule cette planification. - Débitez un moyen enregistré en définissant
payment_method_idsur le brouillon. Pour un total positif, l’émission ou l’envoi débite à une datecharge_atfuture, sinon à une datedue_atfuture, sinon immédiatement.charge_atdoit être dans le futur et ne peut pas précédersend_at.
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 IDpay_. 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
- Consultez Avant de migrer pour les flux qui doivent rester sur l’API legacy.
- Épinglez les appels natifs à une version publiée correspondant à leurs noms de champs, comme
2026-11-02-1pour ces exemples. - Construisez
itemsà partir de variantes éligibles, en vérifiant les quantités, les prix, la devise et les exigences de produit. - 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.
- Faites correspondre les dates d’échéance, les envois planifiés et les frais acheteur selon leur comportement, pas seulement leurs noms de champs.
- Gardez distincts les ID natifs
pay_et les ID legacyinv_. Conservez les lectures legacy sur la version antérieure. - Lisez les montants dans les objets monétaires et ouvrez le checkout avec le
checkout_linksigné. - Gérez
overdueet les statuts de paiement supplémentaires. - Traitez la commande à partir de
payment.succeededpour l’ID de paiement de la facture. - 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.
