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 parpay_ 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.
- 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.
- 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.
- 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.
- Vous traitez la commande à partir du webhook
payment.succeeded.
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.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 avecPOST /invoices.
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
quantitypour 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.
quantityest 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.
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 avecPATCH /invoices/{id}. N’envoyez que les champs que vous modifiez.
itemsremplace 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_idsupprime l’adresse de facturation et le moyen de paiement enregistrés, sauf si vous en envoyez de nouveaux. Cela conserverecipient_emails: envoyez donc aussi une nouvelle liste, sinon le client précédent recevra toujours l’e-mail de facture. email_addressetcustomer_namene sont pas acceptés. Envoyez un autremember_idpour facturer quelqu’un d’autre.- Un brouillon avec un envoi planifié n’accepte qu’une modification de
recipient_emailstant 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 estopenouuncollectible. Toute autre modification est refusée avec une erreur400.
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 avecpayment_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 :
- Effectue les mêmes vérifications que Create Payment sur un moyen de paiement enregistré.
- Réserve le stock pour les quantités facturées et prépare les frais du paiement.
- Renvoie la facture en tant que
openet débite le moyen de paiement hors session. Le débit a lieu aucharge_atque vous transmettez à Issue Invoice ou Send Invoice, sinon àdue_atsi cette date n’est pas encore passée, sinon immédiatement.scheduled_charge_atindique un débit encore à venir.
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 factureopen 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.
Émettre la facture
Issue Invoice transforme un brouillon en facture ouverte. Whop vérifie à nouveau la facture, calcule la taxe finale, et définitstatus 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_amountvautnullsur un brouillon et est défini une fois la facture émise.totaletamount_duel’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.createdest déclenché une seule fois pour l’IDpay_de la facture.- Émettre à nouveau est sans risque. Émettre une facture déjà
openrelance 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.
Obtenir le lien de checkout
Une facture émise etopen 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.Envoyer, planifier et relancer
Send Invoice envoie une facture par e-mail avecPOST /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.
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.
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_emailssur une factureopenarrête ses relances restantes.
Quand Whop débite au lieu d’envoyer un e-mail
Un brouillon avec unpayment_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 erreur429 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, transmettezsend_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_atdoit ê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_atpour 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_emailsfonctionne 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_atrepasse à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é.
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 unedue_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 avecGET /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écessitepayment:basic:read et fonctionne quel que soit le statut.
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.- 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 surinitial_priceplusrenewal_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. Leinitial_pricede la ligne indique cette part ponctuelle deunit_amount, et la page de facture, l’e-mail et le PDF la listent sur une ligne Upfront fee distincte. - 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. - 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.
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 letrial_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_priceplusrenewal_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. Untrial_period_daysau 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 aveccollection_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éfinissezsplit_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 facturent 115 , 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 facturedraft, 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 facturedraft 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.
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 IDpay_. 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 :
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
blockle refuse, et une règleallowl’exempte de vos autres règles. Les règlesreviewetenforce_3dssont 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.
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
quantityen 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.
