Skip to main content
Une facture est une note numérotée portant sur une ou plusieurs de vos variantes, adressée à un client. Une variante est une configuration de prix et de facturation que vous vendez, généralement pour un produit. Son ID commence par plan_, et les éléments de facture la reçoivent sous la forme plan_id. Utilisez une facture lorsque vous convenez d’un prix avec un client avant qu’il ne paie, par exemple pour un devis, une prestation de service ou une commande professionnelle. Vous construisez un brouillon jusqu’à ce qu’il soit correct, puis vous l’émettez pour figer les totaux et l’ouvrir au paiement. L’envoyer fait la même chose et l’envoie par e-mail en un seul appel. Pour en envoyer une depuis votre tableau de bord sans code, consultez Créer et envoyer des factures.
Les factures de cette page nécessitent Api-Version-Date: 2026-10-24 ou une version ultérieure sur chaque requête. Les requêtes avec une version antérieure atteignent l’ancienne API de factures, qui fonctionne différemment. Consultez Avant de commencer.

Fonctionnement d’une facture

Une facture native est un paiement. Son ID commence par pay_ et reste le même après le paiement du client : vous pouvez donc aussi la lire avec Retrieve Payment. Chaque facture reçoit également le numéro suivant dans la séquence propre à votre compte, par exemple #00000042, ou #ACME-00000042 lorsque votre compte dispose d’un préfixe de facture.
  1. Vous créez un brouillon avec des éléments, un client et des informations de facturation. Un brouillon ne débite rien et n’envoie aucun e-mail.
  2. Vous l’émettez, ou vous l’envoyez. L’émission calcule la taxe finale et ouvre la facture au paiement. L’envoi l’émet et l’envoie par e-mail, immédiatement ou à une date que vous planifiez.
  3. Le client paie. Whop débite le moyen de paiement enregistré du client dès que vous émettez ou envoyez la facture, ou bien le client paie via le checkout hébergé de Whop.
  4. Vous traitez la commande à partir du webhook payment.succeeded.
Les factures portent sur des variantes à achat immédiat, c’est-à-dire celles avec release_method: buy_now plutôt qu’une liste d’attente. Une variante ponctuelle est facturée une seule fois, et une variante récurrente démarre un abonnement lorsque la facture est payée. Consultez Facturer un abonnement, qui explique aussi comment l’arrêter après un nombre défini de paiements.

Avant de commencer

Envoyer la version de l’API

/invoices sert deux API différentes, et l’Api-Version-Date à laquelle votre requête correspond détermine laquelle répond. L’émission, l’envoi, l’annulation d’un envoi planifié et la génération d’un PDF n’existent que dans l’API native : ils atteignent donc les factures natives quelle que soit la version envoyée. Les chemins communs aux deux API, comme GET /invoices et POST /invoices/{id}/void, suivent la version. Envoyez l’en-tête sur chaque requête plutôt que de vous fier à l’épinglage d’une clé, afin qu’un changement de clé ne vous fasse jamais basculer d’une API à l’autre. Versions de l’API explique l’épinglage et le changelog. L’API native ne liste ni ne récupère les anciennes factures inv_, et l’ancienne API ne renvoie pas les factures natives.

Appeler l’API

Les exemples de cette page appellent l’API via un petit helper qui envoie l’en-tête de version sur chaque requête.
Envoyez une Idempotency-Key sur chaque POST afin qu’une nouvelle tentative ne crée jamais une seconde facture ni ne répète une action. Generate Invoice PDF fait exception : chaque appel crée un nouveau fichier, il ne rejoue donc pas les réponses.

Créer un brouillon

Create Invoice enregistre un brouillon avec POST /invoices.
La réponse est 201 Created avec le brouillon. Créer un brouillon ne débite rien, n’envoie aucun e-mail et n’envoie aucun webhook. Cette réponse présente un sous-ensemble des champs :
account_id est le compte qui émet la facture, préfixé biz_. Une clé API de compte peut l’omettre pour utiliser son propre compte. Create Invoice liste tous les champs de requête et de réponse. Un brouillon consomme son numéro dès sa création : un brouillon que vous abandonnez laisse donc un trou dans votre séquence. Pour abandonner un brouillon, supprimez-le. Pour le conserver dans votre liste, annulez-le plutôt.

Ajouter des éléments

items accepte de 1 à 50 éléments. Chaque élément prend soit plan_id pour une variante existante, soit plan pour en trouver ou en créer une inline, ainsi qu’une quantity facultative. Un plan inline utilise la même entrée « trouver ou créer » que Create Payment, par exemple { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Il nécessite plan:create, et un product inline nécessite également la permission produit, access_pass:create ou access_pass:update. La création et la mise à jour refusent les éléments qui enfreignent ces règles :
  • Chaque élément est une variante à achat immédiat de votre compte. Une variante n’apparaît qu’une fois : utilisez quantity pour plusieurs unités.
  • Aucune variante n’est archivée, et l’émission ou l’envoi d’un brouillon le vérifie à nouveau : désarchivez la variante ou choisissez-en une autre.
  • quantity est comprise entre 1 et 999 999, et supérieure à 1 uniquement pour une variante qui autorise plusieurs quantités. Ce n’est pas le cas des variantes récurrentes : la quantité d’un élément récurrent est donc 1.
  • Une variante récurrente doit appartenir à un produit.
  • Tous les éléments utilisent la même devise.
  • Dans une facture comportant plusieurs éléments, chaque élément associé à un produit doit être un produit standard (le type de produit standard), et non une app. Les éléments récurrents partagent une même période de facturation, une même durée d’essai gratuit et un même split_pay_required_payments, et tous les éléments nécessitent des paramètres de paiement, de taxe et d’accès compatibles. Les variantes avec des champs personnalisés ou un mot de passe ne peuvent pas être combinées. Les éléments sans produit, comme des frais personnalisés, peuvent côtoyer les autres.
Chaque ligne de la réponse possède un label, qui correspond au titre du produit, ou au titre de la variante pour une variante sans produit. L’e-mail, le PDF et le checkout l’affichent. Le brouillon conserve le prix de chaque variante au moment où vous avez enregistré ses éléments : une modification ultérieure du prix de la variante ne change donc pas la facture. Un élément ponctuel est facturé à son prix. À partir de la version d’API 2026-11-11, la création ou le remplacement d’un élément récurrent inclut son initial_price plus son renewal_price dans la première facture. Les épinglages de versions antérieures utilisent uniquement le prix de renouvellement. Les modifications qui omettent items conservent les prix enregistrés.

Définir le client et les informations de facturation

Envoyez member_id ou email_address, et billing_address ou mailing_address_id, jamais les deux d’une même paire. Une adresse de facturation nécessite un client. Un client est facultatif sur un brouillon et obligatoire pour l’émettre. Whop calcule la taxe lorsque vous émettez la facture, en utilisant l’adresse de facturation pour localiser le client. Lorsqu’une taxe s’applique et que Whop ne peut pas déterminer où se trouve le client, l’émission est refusée : ajoutez donc une adresse de facturation dès que vous collectez des taxes.

Modifier un brouillon

Update Invoice modifie un brouillon avec PATCH /invoices/{id}. N’envoyez que les champs que vous modifiez.
  • items remplace toute la liste et lit le prix actuel de chaque variante. Omettez-le pour conserver les éléments et les prix enregistrés.
  • Changer member_id supprime l’adresse de facturation et le moyen de paiement enregistrés, sauf si vous en envoyez de nouveaux. Cela conserve recipient_emails : envoyez donc aussi une nouvelle liste, sinon le client précédent recevra toujours l’e-mail de facture.
  • email_address et customer_name ne sont pas acceptés. Envoyez un autre member_id pour facturer quelqu’un d’autre.
  • Un brouillon avec un envoi planifié n’accepte qu’une modification de recipient_emails tant que vous n’annulez pas l’envoi.
  • Une fois la facture émise, la seule modification possible est recipient_emails, envoyé seul, et uniquement tant que la facture est open ou uncollectible. Toute autre modification est refusée avec une erreur 400.

Choisir comment le client paie

Il existe deux façons d’être payé pour une facture émise. Choisissez-en une avant de l’émettre, car le moyen de paiement enregistré se définit sur le brouillon. Une facture émise reçoit un checkout_link même si elle comporte un moyen de paiement enregistré. Si le débit automatique échoue, le client peut toujours payer via le checkout.

Débiter un moyen de paiement enregistré

Placez un moyen de paiement enregistré sur le brouillon avec payment_method_id. Il doit s’agir de l’un des moyens enregistrés du client. Enregistrer des moyens de paiement montre comment un client en enregistre un, et List payment methods permet de trouver ceux d’un membre. Lorsque vous émettez ou envoyez la facture et que son total est supérieur à zéro, Whop :
  1. Effectue les mêmes vérifications que Create Payment sur un moyen de paiement enregistré.
  2. Réserve le stock pour les quantités facturées et prépare les frais du paiement.
  3. Renvoie la facture en tant que open et débite le moyen de paiement hors session. Le débit a lieu au charge_at que vous transmettez à Issue Invoice ou Send Invoice, sinon à due_at si cette date n’est pas encore passée, sinon immédiatement. scheduled_charge_at indique un débit encore à venir.
La réponse ne vous indique pas si le débit a réussi. Traitez la commande à partir du webhook payment.succeeded pour l’ID pay_ de la facture. Une facture payée finalise l’adhésion, et vos metadata figurent sur le débit et sur l’adhésion. Règles de paiement sur les paiements de factures explique comment vos règles de paiement filtrent le débit.

Si le débit automatique est refusé

Un débit refusé laisse la facture open et restitue le stock réservé. Récupérez la facture en tant que paiement et lisez failure_message pour savoir pourquoi la dernière tentative a échoué. Lorsque le débit est refusé ou nécessite une action du client, Whop envoie par e-mail le lien de paiement de la facture à ses destinataires, afin que le client puisse payer via le checkout à la place. C’est le seul e-mail que Whop envoie pour une facture que vous émettez sans l’envoyer. Il nécessite un checkout_link et au moins une entrée dans recipient_emails, et il n’est pas comptabilisé dans la limite d’envoi.
Un débit hors session ne peut pas présenter d’authentification 3D Secure au client. Si sa banque en exige une, le débit automatique n’aboutit pas, et la facture reste impayée jusqu’à ce que le client s’authentifie ou paie autrement.

Émettre la facture

Issue Invoice transforme un brouillon en facture ouverte. Whop vérifie à nouveau la facture, calcule la taxe finale, et définit status sur open et totals_status sur final. Lorsque la facture comporte un moyen de paiement enregistré et un total supérieur à zéro, Whop le débite ensuite, comme décrit dans Débiter un moyen de paiement enregistré.
  • La taxe devient définitive. tax_amount vaut null sur un brouillon et est défini une fois la facture émise. total et amount_due l’incluent.
  • Whop crée l’adhésion du client lorsque la facture porte sur un produit. Elle reste à l’état de brouillon, sans accès, jusqu’au paiement de la facture. Une facture dont aucun élément n’a de produit ne reçoit pas d’adhésion.
  • payment.created est déclenché une seule fois pour l’ID pay_ de la facture.
  • Émettre à nouveau est sans risque. Émettre une facture déjà open relance les mêmes vérifications et, si elles réussissent, la renvoie inchangée : ses totaux restent les mêmes et rien n’est débité à nouveau.
  • L’émission n’envoie pas la facture par e-mail, hormis le lien de paiement après un débit refusé. Pour envoyer la facture par e-mail, envoyez-la plutôt, ou transmettez vous-même le lien de checkout.
Une émission refusée ne modifie rien et ne débite rien. Corrigez la cause et émettez à nouveau la facture. Erreurs d’émission liste les raisons possibles. Une facture émise et open porte un checkout_link, une valeur signée de la forme pay_xxxxxxxxxxxxx.<signature>. Il ouvre la facture sur le checkout hébergé de Whop à son prix fixe.
1

Lire le lien depuis la facture émise

checkout_link vaut null sauf si la facture est open : les brouillons et les factures payées, annulées ou irrécouvrables n’en ont donc pas. Il vaut aussi null pour une facture adressée à un acheteur professionnel, pour une facture dont l’adhésion a été annulée, et lorsque vos identifiants n’ont pas payment:charge. Un acheteur professionnel est un client qui est un autre compte Whop plutôt qu’une personne.
2

Construire l'URL du checkout hébergé

Coupez le lien à son premier . : l’ID pay_ de la facture se trouve avant, et le jeton après.
3

L'envoyer au client

Envoyez la facture pour que Whop envoie le lien par e-mail, ou placez l’URL dans votre propre e-mail ou page de facture. Seul le client de la facture peut payer via ce lien. Toute autre personne est refusée et invitée à se connecter en tant que client de la facture. Le lien cesse de fonctionner une fois la facture payée, annulée ou marquée comme irrécouvrable.
4

Traiter la commande depuis le webhook

Écoutez payment.succeeded pour l’ID pay_ de la facture, comme pour le débit automatique. Webhooks présente un handler.
Le checkout affiche le numéro et la date d’échéance de la facture à côté de ses éléments, et la date d’échéance passe au rouge une fois dépassée. Le client paie les éléments et le total de la facture et ne peut pas ajouter de code promo.

Envoyer, planifier et relancer

Send Invoice envoie une facture par e-mail avec POST /invoices/{id}/send. L’envoi d’un brouillon l’émet d’abord, comme Issue Invoice. L’envoi d’une facture open la renvoie par e-mail.
L’e-mail affiche le nom et le logo de votre compte, le numéro de facture, le total, la date d’échéance, chaque élément et un bouton qui ouvre le checkout de la facture. Whop n’envoie par e-mail qu’une facture que le client peut payer depuis l’e-mail. Une facture open doit avoir un checkout_link pour être envoyée, et un brouillon nécessite un client qui n’est pas un acheteur professionnel. Un brouillon adressé à un acheteur professionnel peut tout de même être envoyé s’il comporte un moyen de paiement enregistré, car celui-ci est débité à la place.

Qui reçoit l’e-mail

Chaque envoi adresse un e-mail distinct à chaque adresse, une seule fois, afin que les destinataires ne voient jamais les adresses des autres. Les adresses sont :
  • L’e-mail du compte Whop du client, que le PDF de la facture imprime sous Bill to.
  • Chaque entrée de recipient_emails.
Whop enregistre recipient_emails en minuscules et dédoublonne la liste : une adresse présente aux deux endroits reçoit donc un seul e-mail. Un recipient_emails vide signifie que Whop n’envoie d’e-mail à personne, client compris. Utilisez-le pour empêcher Whop d’envoyer une facture par e-mail :
  • Send Invoice refuse la facture, sauf si elle débite un moyen de paiement enregistré à la place.
  • Aucun lien de paiement n’est envoyé après un débit refusé.
  • Aucune relance n’est envoyée. Vider recipient_emails sur une facture open arrête ses relances restantes.

Quand Whop débite au lieu d’envoyer un e-mail

Un brouillon avec un payment_method_id et un total supérieur à zéro est débité au lieu d’être envoyé par e-mail, comme lors de son émission. Si le débit automatique est refusé explique ce qui se passe en cas d’échec du débit. Un tel brouillon peut être envoyé avec un recipient_emails vide, puisque personne n’a besoin de l’e-mail.

Limite d’envoi

Chaque facture peut être envoyée par e-mail trois fois en 24 heures, y compris l’envoi qui l’a émise. Un quatrième envoi dans cet intervalle est refusé avec une erreur 429 dont le error.code est invoice_send_limit_reached. Les relances, le lien de paiement après un débit refusé et un envoi qui débite au lieu d’envoyer un e-mail ne sont pas comptabilisés dans la limite.

Planifier un envoi

Pour envoyer un brouillon plus tard, transmettez send_at. Le brouillon reste un brouillon et affiche l’heure dans scheduled_send_at. À ce moment-là, Whop l’envoie comme si vous aviez appelé Send Invoice.
  • Seul un brouillon peut être planifié, et send_at doit être dans le futur. Whop vérifie les destinataires et le lien de paiement au moment de la planification, comme pour un envoi immédiat.
  • Envoyez à nouveau avec un nouveau send_at pour déplacer l’heure.
  • La modification est verrouillée jusqu’à ce que l’envoi ait lieu ou que vous l’annuliez. Une mise à jour qui ne modifie que recipient_emails fonctionne toujours, mais elle ne peut pas retirer le dernier destinataire d’un brouillon qui ne sera pas débité.
  • Cancel Scheduled Send avec POST /invoices/{id}/unschedule. scheduled_send_at repasse à null, et le brouillon peut de nouveau être modifié. Annuler une facture sans envoi planifié la renvoie inchangée.
  • Annuler (void) un brouillon planifié arrête son envoi planifié.
Whop vérifie les envois arrivés à échéance chaque minute : un envoi planifié part donc environ une minute après send_at. S’il est refusé, par exemple parce qu’une variante a été supprimée depuis la planification, la facture reste un brouillon, scheduled_send_at repasse à null, et l’API ne renvoie pas la raison. Tout autre échec est retenté environ toutes les 10 minutes, jusqu’à 12 tentatives au total. Tant qu’une tentative n’a pas réussi ou que Whop n’a pas cessé de réessayer, scheduled_send_at affiche l’heure de la prochaine tentative plutôt que null. Lisez la facture après send_at pour confirmer qu’elle est open.

Relances

Lorsque Send Invoice envoie par e-mail une facture qui a une due_at, Whop planifie aussi des relances 1, 3, 7, 14, 30 et 60 jours après due_at, en ignorant celles dont la date est déjà passée. Chaque relance est envoyée aux mêmes adresses que la facture et indique depuis combien de jours la facture est en retard. Les relances ne sont envoyées que tant que la facture est open : elles s’arrêtent donc une fois la facture payée, annulée ou marquée comme irrécouvrable. Une relance qui arrive à échéance pendant qu’un paiement est en cours attend la fin du paiement. Une facture que vous émettez sans l’envoyer, ou qui est débitée au lieu d’être envoyée par e-mail, ne reçoit aucune relance.

Historique des e-mails

List Invoice Sends renvoie les lots d’e-mails enregistrés avec GET /invoices/{id}/sends, du plus récent au plus ancien. Il inclut les e-mails initiaux et répétés, les e-mails planifiés, les relances et les suivis de paiement après un débit échoué sur un moyen de paiement enregistré. Utilisez la première entrée pour l’envoi enregistré le plus récent, et page_info.end_cursor comme after pour lire les entrées plus anciennes. Les lots manuels utilisent send lorsque la facture n’a pas d’historique d’e-mails terminé antérieur, et resend sinon. Le type est déterminé au moment où le lot terminé est enregistré : les requêtes mises en file ensemble sont donc classées dans l’ordre de leur achèvement. Les e-mails antérieurs non enregistrés restent inconnus. Chaque entrée contient kind, sent_at, recipient_count, recipients et actor. La lecture de l’historique nécessite payment:basic:read. Les adresses nécessitent aussi member:email:read. Sans cette permission, recipients est vide. L’expéditeur nécessite aussi company:authorized_user:read. Sinon, actor est null. Les envois automatiques et les clés API de compte ont également un actor null. Le worker ajoute une entrée après avoir soumis l’ensemble du lot pour livraison. Pour un lot partiel, il n’ajoute une entrée que si une nouvelle tentative complète le lot. L’entrée conserve la liste de destinataires d’origine. Un lot enregistré ne confirme pas la livraison en boîte de réception. Le service d’envoi peut supprimer des messages si la facture ou les destinataires changent avant la livraison. L’historique exclut les e-mails envoyés avant l’introduction de cette fonctionnalité. Émettre une facture sans l’envoyer par e-mail n’ajoute aucune entrée à l’historique.

Télécharger un PDF

Generate Invoice PDF génère la facture au format PDF et renvoie un lien temporaire vers celle-ci. Il nécessite payment:basic:read et fonctionne quel que soit le statut.
La réponse contient url et expires_at. Le lien fonctionne pendant 15 minutes, et toute personne qui le détient peut télécharger le fichier. Générez-en un nouveau lorsqu’il expire. Le PDF met votre entreprise en avant : le nom de votre compte figure en tête de page, et le pied de page indique que Whop Inc émet la facture en votre nom et pour votre compte. Il affiche le numéro de facture, sa date et sa date d’échéance, ainsi que les informations Bill to. Chaque élément affiche sa quantité, son prix unitaire et son montant, suivis du sous-total, des frais de service, de la taxe et du montant dû. Une facture comportant un élément récurrent indique aussi le montant du renouvellement et sa fréquence. Le PDF d’un brouillon affiche ses totaux estimés, avec une taxe à zéro jusqu’à l’émission. Certains contenus dépendent des permissions de vos identifiants :

Facturer un abonnement

Placez une variante récurrente sur une facture pour démarrer un abonnement lorsque le client la paie. Whop le renouvelle ensuite une fois par période de facturation.
  1. La facture couvre la première période et les éventuels frais initiaux. Un élément récurrent doit appartenir à un produit et a une quantité de 1. À partir de la version d’API 2026-11-11, sa première facture porte sur initial_price plus renewal_price. Le paiement démarre immédiatement la première période de facturation payante, sauf si la variante comporte un essai gratuit. L’abonnement démarre alors par l’essai. Dans le tableau de bord, un élément récurrent personnalisé dispose d’un champ facultatif Upfront fee. Le initial_price de la ligne indique cette part ponctuelle de unit_amount, et la page de facture, l’e-mail et le PDF la listent sur une ligne Upfront fee distincte.
  2. Le paiement de la facture démarre l’abonnement, que Whop débite le moyen de paiement enregistré à l’émission ou que le client paie via le checkout_link. La première période commence au paiement. Le checkout ouvert depuis le lien indique le montant du renouvellement, frais acheteur de la facture compris, et sa fréquence.
  3. Chaque renouvellement est encaissé selon la méthode choisie lors de l’émission ou de l’envoi de la facture. Il ne facture que les éléments récurrents, avec les frais acheteur de la facture, au prix de renouvellement de chaque variante au moment de l’émission. Celui-ci peut différer du prix enregistré sur le brouillon si le prix de la variante a changé après l’enregistrement des éléments. Les éléments ponctuels ne sont facturés qu’une fois.
Transmettez collection_method à Issue Invoice ou Send Invoice pour choisir comment les renouvellements sont encaissés. Un envoi planifié applique le collection_method avec lequel vous l’avez planifié, que le brouillon affiche dans scheduled_collection_method. send_invoice nécessite au moins une adresse dans recipient_emails et n’est pas disponible pour les factures adressées à une entreprise. Tant qu’il s’applique, le dernier destinataire de la facture ne peut pas être retiré. Une facture sans élément récurrent refuse collection_method. Payer la première facture par carte conserve send_invoice. Chaque renouvellement est un paiement distinct, avec son propre ID pay_ et ses propres webhooks payment.*. Un renouvellement charge_automatically n’est pas une facture numérotée : il n’apparaît donc pas dans List Invoices. Un renouvellement send_invoice est une facture numérotée dans List Invoices, et Whop ne la débite pas automatiquement. L’abonnement reste past_due jusqu’à ce que le client paie via le checkout_link de la facture. Le client conserve son accès entre-temps. Annulez l’adhésion pour arrêter les renouvellements. Une fois l’adhésion annulée, le checkout_link d’une facture de renouvellement ouverte cesse de fonctionner. Pour trouver l’abonnement, récupérez la facture en tant que paiement et lisez son membership_id, ce qui nécessite member:basic:read.

Commencer par un essai gratuit

Une facture respecte le trial_period_days d’une variante récurrente, comme le fait le checkout. La première facture ne porte que sur le initial_price de la variante. Son paiement démarre l’essai, et le premier renouvellement facture renewal_price à la fin de l’essai. Les factures créées avant le 16/11/2026 à 17:00 UTC facturent la première période et ignorent l’essai.
  • Un client qui avait déjà un abonnement à la variante ne bénéficie pas d’essai. Sa première facture porte sur initial_price plus renewal_price. Les factures de renouvellement ne démarrent jamais d’essai.
  • L’essai provient de la variante. Pour un élément récurrent personnalisé, définissez variant.trial_period_days. Un trial_period_days au niveau de l’élément est refusé.
  • Tous les éléments récurrents de la facture doivent avoir la même durée d’essai.
  • Lorsque la facture ne débite rien, émettez-la ou envoyez-la avec un payment_method_id, ce qui démarre l’essai immédiatement, ou avec collection_method: "send_invoice".
  • Dans le tableau de bord, un élément récurrent personnalisé dispose d’un champ Free trial days. Le plan de facturation d’un produit affiche son propre essai.

Arrêter après un nombre défini de paiements

Pour facturer un plan de paiement fixe, par exemple six mensualités, définissez split_pay_required_payments sur la variante récurrente, de 2 à 115. La facture constitue le premier paiement, frais initiaux compris. Par exemple, des frais initiaux de 75 avectroisversementsde40avec trois versements de 40 facturent 115 ,puis40, puis 40 , puis 40 $. Whop cesse de renouveler une fois ce nombre de paiements atteint, et l’adhésion reste active. Le client ne peut pas annuler lui-même l’abonnement avant cette échéance, mais vous le pouvez. Laissez ce champ vide pour renouveler jusqu’à l’annulation de l’abonnement.

Statuts et cycle de vie

status prend ses valeurs parmi celles des paiements : une facture peut donc aussi afficher un état de paiement comme pending pendant qu’un paiement est en cours. totals_status vous indique si les champs monétaires sont définitifs : estimated tant que la facture est un brouillon, final après son émission. overdue vaut true pour une facture open ou uncollectible dont la due_at est dépassée.

Annuler ou marquer comme irrécouvrable

Void Invoice annule une facture draft, open ou uncollectible. Annuler une facture déjà annulée la renvoie inchangée, et une facture payée ne peut pas être annulée. Marquez une facture comme irrécouvrable pour indiquer que vous ne pensez pas l’encaisser. Seule une facture open peut être marquée, et marquer à nouveau une facture irrécouvrable la renvoie inchangée. Une facture irrécouvrable n’a pas de checkout_link et ne reçoit aucune relance. Cet exemple marque une facture open comme irrécouvrable, puis l’annule :

Supprimer une facture

Delete Invoice supprime une facture draft ou void avec DELETE /invoices/{id}. La réponse est { id, deleted: true }. Une facture supprimée n’apparaît plus dans List Invoices ni dans List Payments, et son ID renvoie une erreur 404. Une suppression est irréversible. Annulez une facture open avant de la supprimer. Un brouillon avec un envoi ou un débit planifié nécessite d’abord Cancel Scheduled Send. Un brouillon de facture de renouvellement ne peut pas être supprimé tant qu’il facture un abonnement. Une facture annulée qui a encaissé de l’argent ou qui attend encore un virement bancaire ne peut pas être supprimée, pas plus qu’une facture payée, en attente ou irrécouvrable. Le champ deletable d’une facture vaut true lorsqu’elle peut être supprimée. La suppression nécessite invoice:update ou payment:charge. Le numéro d’un brouillon supprimé n’est pas réutilisé.

Lister et récupérer des factures

List Invoices renvoie les factures que vos identifiants peuvent lire, de la plus récente à la plus ancienne. Une clé API voit son propre compte, et un jeton utilisateur voit tous les comptes dont l’utilisateur peut lire les paiements. Affinez la liste avec ces paramètres de requête : Un brouillon planifié est un brouillon qui a un scheduled_send_at. Une facture open n’est jamais planifiée, pas plus qu’un brouillon envoyé à sa date d’échéance. Triez avec order (created_at, due_at ou scheduled_send_at) et direction (asc ou desc). Un tri par due_at ou scheduled_send_at place en dernier les factures sans cette date. La réponse est { data, page_info }. Tant que page_info.has_next_page vaut true, transmettez page_info.end_cursor comme after pour lire la page suivante.
Retrieve Invoice lit une facture à partir de son ID pay_. List Payments exclut les brouillons. Pour exporter des factures dans un fichier CSV, appelez Create Export avec resource: "receipt_invoices". Cela nécessite payment:basic:read et payment:basic:export. Les colonnes client n’apparaissent que si vos identifiants disposent aussi de member:basic:read ou member:email:read.

Webhooks

Les factures natives envoient des webhooks de paiement pour leur ID pay_. Les événements invoice.* appartiennent à l’ancienne API de factures, et les factures natives ne les envoient pas. D’autres événements payment.*, comme payment.failed, peuvent aussi arriver pour l’ID pay_ de la facture à mesure que ses tentatives de paiement évoluent. Abonnez-vous à ces événements à l’aide du guide des webhooks. Pour traiter une commande, enregistrez l’id de la facture avec la commande lors de la création du brouillon. Le data d’un événement payment.succeeded est le paiement : data.id est donc l’ID pay_ de la facture. Après avoir vérifié l’événement, recherchez la commande à partir de cet ID. Dans ce handler, orders représente votre propre stockage de commandes :
Vérifier fulfilled empêche un événement relivré de traiter la commande deux fois. Les renouvellements d’abonnement ont leurs propres ID pay_ : ils ne correspondent donc pas à une facture.

Règles de paiement sur les paiements de factures

Vos règles de paiement s’exécutent sur les paiements de factures après le filtrage antifraude propre à Whop, comme sur n’importe quel checkout. Ce qu’elles peuvent faire dépend de la présence ou non du client.
  • Le débit automatique à l’émission a lieu hors session. Une règle block le refuse, et une règle allow l’exempte de vos autres règles. Les règles review et enforce_3ds sont ignorées, car le débit a lieu hors session.
  • Un paiement via le lien de checkout a lieu en session. Les quatre actions s’appliquent, avec les limites d’éligibilité décrites dans Gérer la fraude.
Pour le débit automatique, les conditions de carte lisent le moyen de paiement enregistré et les conditions de facturation lisent l’adresse de facturation de la facture. customer_email est l’e-mail du compte Whop du client. Le champ payment_rule_matches du paiement liste la règle qui a statué. Une règle ignorée n’est pas listée.

Les factures dans le tableau de bord

La page Invoices liste, crée et envoie des factures natives. Les anciennes factures se trouvent dans son onglet Legacy invoices, décrit dans Envoyer une facture.

Permissions

Chaque écriture nécessite payment:charge, la même permission que Create Payment, et chaque lecture nécessite payment:basic:read. Les permissions invoice:* appartiennent à l’ancienne API de factures, et les factures natives ne les utilisent pas. Une création ou une mise à jour qui envoie un élément plan inline nécessite aussi plan:create. Certains champs nécessitent leur propre permission. Sans elle, le champ est renvoyé à null, et recipient_emails est renvoyé vide. Si vos identifiants perdent l’une de ces permissions de lecture après un POST, le rejouer avec la même Idempotency-Key est refusé avec une erreur 403 dont le error.code est invoice_replay_permission_revoked lorsque la réponse stockée affiche ces champs. Récupérez plutôt la facture avec GET. Ajoutez des permissions depuis le guide des permissions.

Erreurs

Les refus sont renvoyés sous la forme { error: { type, message, code } }. Chaque code ci-dessous correspond à une erreur 400, sauf indication contraire. Un plan_id, member_id, mailing_address_id ou payment_method_id inconnu renvoie une 404, et un horodatage que Whop ne peut pas lire renvoie une 400 avec invalid_timestamp. Ces refus sont des erreurs 400 sans error.code : lisez donc error.message pour connaître la raison :
  • Un champ de premier niveau inconnu.
  • Une quantity en dehors de la plage 1 à 999 999.
  • Une adresse invalide dans recipient_emails, ou plus de 50 adresses.
  • Une règle multi-éléments non respectée, comme une incohérence de période de facturation.

Erreurs de création et de mise à jour

Erreurs d’émission

Erreurs d’envoi et de planification

L’envoi d’un brouillon l’émet : un envoi peut donc aussi être refusé pour n’importe quelle raison figurant dans Erreurs d’émission.

Autres erreurs

L’annulation d’une facture payée renvoie une erreur 400 sans code.

Prochaines étapes

Référence de l'API Invoices

Chaque endpoint, paramètre et champ de réponse des factures.

Enregistrer des moyens de paiement

Collectez le moyen de paiement enregistré qu’une facture débite à l’émission.

Gérer la fraude

Rédigez les règles de paiement qui filtrent les paiements de factures.

Écouter les webhooks

Suivez payment.created et payment.succeeded pour vos factures.