plan_ en factuuritems accepteren het als plan_id. Gebruik een factuur wanneer je vóór de betaling een prijs met een klant afspreekt, zoals bij een offerte, een dienst of een zakelijke bestelling. Je werkt een concept bij tot het klopt en geeft het daarna uit om de totalen vast te leggen en het open te stellen voor betaling. Verzenden doet dat en mailt de factuur in één aanroep. Zie Facturen maken en verzenden om er een zonder code vanuit je dashboard te verzenden.
Facturen op deze pagina hebben bij elk verzoek
Api-Version-Date: 2026-10-24 of later nodig. Verzoeken met een eerdere versie komen bij de legacy-factuur-API terecht, die anders werkt. Zie Voordat je begint.Hoe een factuur werkt
Een native factuur is een betaling. Het ID begint metpay_ en blijft hetzelfde nadat de klant heeft betaald, dus je kunt de factuur ook lezen met Retrieve Payment. Elke factuur krijgt ook het volgende nummer in de eigen reeks van je account, zoals #00000042, of #ACME-00000042 als je account een factuurprefix heeft.
- Je maakt een concept met items, een klant en factuurgegevens. Een concept brengt niets in rekening en mailt niemand.
- Je geeft het uit of verzendt het. Uitgeven berekent de definitieve belasting en stelt de factuur open voor betaling. Verzenden geeft de factuur uit en mailt deze, nu of op een tijdstip dat je inplant.
- De klant betaalt. Whop belast de opgeslagen betaalmethode van de klant zodra je de factuur uitgeeft of verzendt, of de klant betaalt via de gehoste checkout van Whop.
- Je levert de bestelling uit vanuit de webhook
payment.succeeded.
release_method: buy_now in plaats van een wachtlijst. Een eenmalige variant wordt één keer gefactureerd en een terugkerende variant start een abonnement wanneer de factuur is betaald. Zie Een abonnement factureren, waar ook staat hoe je het na een vast aantal betalingen stopt.
Voordat je begint
De API-versie meesturen
/invoices bedient twee verschillende API’s, en de Api-Version-Date waarnaar je verzoek wordt herleid, bepaalt welke antwoordt.
Uitgeven, verzenden, een geplande verzending annuleren en een pdf genereren bestaan alleen in de native API, dus die bereiken native facturen, ongeacht welke versie je stuurt. De paden die beide API’s hebben, zoals
GET /invoices en POST /invoices/{id}/void, volgen de versie.
Stuur de header bij elk verzoek mee in plaats van te vertrouwen op de pin van een sleutel, zodat het wisselen van sleutels je nooit tussen de twee laat verspringen. API-versies legt pins en de changelog uit.
De native API geeft geen legacy
inv_-facturen weer en haalt ze niet op, en de legacy-API retourneert geen native facturen.
De API aanroepen
De voorbeelden op deze pagina roepen de API aan via een kleine helper die bij elk verzoek de versieheader meestuurt.POST een Idempotency-Key mee, zodat een nieuwe poging nooit een tweede factuur aanmaakt of een actie herhaalt. Generate Invoice PDF is de uitzondering: elke aanroep maakt een nieuw bestand, dus antwoorden worden niet opnieuw afgespeeld.
Een concept maken
Create Invoice slaat een concept op metPOST /invoices.
201 Created met het concept. Een concept aanmaken brengt niets in rekening, verstuurt geen e-mail en verstuurt geen webhook. Dit antwoord toont een deel van de velden:
account_id is het account dat de factuur uitgeeft, met het voorvoegsel biz_. Een account-API-sleutel kan het weglaten om het eigen account te gebruiken. Create Invoice vermeldt elk verzoek- en antwoordveld.
Een concept gebruikt zijn nummer bij het aanmaken, dus een concept dat je weggooit, laat een gat in je reeks achter. Om een concept weg te gooien, verwijder je het. Om het in je lijst te houden, maak je het in plaats daarvan ongeldig.
Items toevoegen
items accepteert 1 tot 50 items. Elk item accepteert ofwel plan_id voor een bestaande variant, ofwel plan om er inline een te vinden of aan te maken, plus een optionele quantity.
Een inline plan gebruikt dezelfde find-or-create-invoer als Create Payment, bijvoorbeeld { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Het vereist plan:create, en een inline product vereist ook de productmachtiging, access_pass:create of access_pass:update.
Aanmaken en bijwerken weigeren items die deze regels overtreden:
- Elk item is een buy-now-variant van je account. Een variant komt één keer voor, dus gebruik
quantityvoor meer eenheden. - Geen enkele variant is gearchiveerd, en uitgeven of verzenden van een concept controleert dit opnieuw, dus haal de variant uit het archief of kies een andere.
quantityligt tussen 1 en 999.999, en is alleen hoger dan 1 voor een variant die meerdere hoeveelheden toestaat. Terugkerende varianten doen dat niet, dus de hoeveelheid van een terugkerend item is 1.- Een terugkerende variant moet bij een product horen.
- Elk item gebruikt dezelfde valuta.
- In een factuur met meerdere items moet elk item met een product een gewoon product zijn (het standaardproducttype), geen app. Terugkerende items delen één factureringsperiode, lengte van de gratis proefperiode en
split_pay_required_payments, en alle items hebben compatibele betalings-, belasting- en toegangsinstellingen nodig. Varianten met aangepaste velden of een wachtwoord kunnen niet worden gecombineerd. Items zonder product, zoals een aangepaste vergoeding, kunnen naast de rest staan.
label, de titel van het product, of de titel van de variant voor een variant zonder product. De e-mail, de pdf en de checkout tonen het.
Het concept behoudt de prijs die elke variant had toen je de items opsloeg, dus een latere prijswijziging van de variant verandert de factuur niet. Een eenmalig item wordt tegen zijn prijs gefactureerd. Vanaf API-versie 2026-11-11 neemt het aanmaken of vervangen van een terugkerend item de initial_price plus renewal_price op in de eerste factuur. Eerdere versiepins gebruiken alleen de verlengingsprijs. Bewerkingen die items weglaten, behouden de opgeslagen prijzen.
De klant en factuurgegevens instellen
Stuur
member_id of email_address, en billing_address of mailing_address_id, nooit beide van een paar. Een factuuradres vereist een klant. Een klant is optioneel bij een concept en verplicht om het uit te geven.
Whop berekent de belasting wanneer je de factuur uitgeeft en gebruikt het factuuradres om de klant te lokaliseren. Als er belasting van toepassing is en Whop niet kan bepalen waar de klant zich bevindt, wordt het uitgeven geweigerd, dus voeg altijd een factuuradres toe wanneer je belasting int.
Een concept bewerken
Update Invoice wijzigt een concept metPATCH /invoices/{id}. Stuur alleen de velden die je wijzigt.
itemsvervangt de hele lijst en leest de huidige prijs van elke variant. Laat het weg om de opgeslagen items en prijzen te behouden.- Het wijzigen van
member_idverwijdert het opgeslagen factuuradres en de opgeslagen betaalmethode, tenzij je nieuwe meestuurt.recipient_emailsblijft behouden, dus stuur ook een nieuwe lijst mee, anders ontvangt de vorige klant nog steeds de factuurmail. email_addressencustomer_nameworden niet geaccepteerd. Stuur een anderemember_idom iemand anders te factureren.- Een concept met een geplande verzending accepteert alleen een wijziging van
recipient_emailstotdat je de verzending annuleert. - Zodra de factuur is uitgegeven, is de enige wijziging die je kunt doen
recipient_emails, los meegestuurd, en alleen zolang de factuuropenofuncollectibleis. Elke andere bewerking wordt geweigerd met een400.
Kiezen hoe de klant betaalt
Er zijn twee manieren om voor een uitgegeven factuur betaald te krijgen. Kies er een voordat je de factuur uitgeeft, omdat de opgeslagen betaalmethode op het concept komt.
Een uitgegeven factuur krijgt een
checkout_link, ook als er een opgeslagen betaalmethode op staat. Als de automatische afschrijving mislukt, kan de klant nog steeds via de checkout betalen.
Een opgeslagen betaalmethode belasten
Zet een opgeslagen betaalmethode op het concept metpayment_method_id. Het moet een van de opgeslagen methoden van de klant zijn. Betaalmethoden opslaan laat zien hoe een klant er een opslaat, en List payment methods vindt de methoden die een lid heeft.
Wanneer je de factuur uitgeeft of verzendt en het totaal hoger is dan nul, doet Whop het volgende:
- Voert dezelfde controles uit die Create Payment uitvoert op een opgeslagen betaalmethode.
- Reserveert voorraad voor de gefactureerde hoeveelheden en bereidt de vergoedingen van de betaling voor.
- Retourneert de factuur als
openen belast de methode off-session. De afschrijving vindt plaats op decharge_atdie je aan Issue Invoice of Send Invoice meegeeft, anders opdue_atzolang die nog in de toekomst ligt, en anders direct.scheduled_charge_attoont een afschrijving die nog moet plaatsvinden.
payment.succeeded-webhook voor het pay_-ID van de factuur. Een betaalde factuur voltooit het lidmaatschap, en je metadata staat op de afschrijving en het lidmaatschap. Betalingsregels bij factuurbetalingen beschrijft hoe je betalingsregels de afschrijving screenen.
Als de automatische afschrijving wordt geweigerd
Een geweigerde afschrijving laat de factuuropen en geeft de gereserveerde voorraad vrij. Haal de factuur op als betaling en lees failure_message om te zien waarom de laatste poging is mislukt.
Wanneer de afschrijving wordt geweigerd of een actie van de klant vereist, mailt Whop de betaallink van de factuur naar de ontvangers, zodat de klant in plaats daarvan via de checkout kan betalen. Het is de enige e-mail die Whop verstuurt voor een factuur die je uitgeeft zonder deze te verzenden. Hiervoor zijn een checkout_link en minstens één item in recipient_emails nodig, en het telt niet mee voor de verzendlimiet.
De factuur uitgeven
Issue Invoice maakt van een concept een open factuur. Whop controleert de factuur opnieuw, berekent de definitieve belasting en zetstatus op open en totals_status op final. Als de factuur een opgeslagen betaalmethode en een totaal boven nul heeft, belast Whop deze vervolgens, zoals beschreven in Een opgeslagen betaalmethode belasten.
- De belasting wordt definitief.
tax_amountisnullbij een concept en wordt ingesteld zodra je het uitgeeft.totalenamount_duebevatten de belasting. - Whop maakt het lidmaatschap van de klant aan wanneer de factuur een product factureert. Het blijft een concept, zonder toegang, totdat de factuur is betaald. Een factuur waarvan geen enkel item een product heeft, krijgt geen lidmaatschap.
payment.createdwordt één keer geactiveerd voor hetpay_-ID van de factuur.- Opnieuw uitgeven is veilig. Een factuur uitgeven die al
openis, voert dezelfde controles opnieuw uit en retourneert de factuur ongewijzigd als ze slagen: de totalen blijven staan en er wordt niets opnieuw afgeschreven. - Uitgeven mailt de factuur niet, behalve de betaallink na een geweigerde afschrijving. Om de factuur te mailen, verzend je deze, of je bezorgt de checkoutlink zelf.
De checkoutlink ophalen
Een uitgegeven factuur met de statusopen heeft een checkout_link, een ondertekende waarde in de vorm pay_xxxxxxxxxxxxx.<signature>. Deze opent de factuur tegen de vaste prijs op de gehoste checkout van Whop.
1
Lees de link uit de uitgegeven factuur
checkout_link is null tenzij de factuur open is, dus concepten en betaalde, ongeldige of oninbare facturen hebben er geen. Het is ook null voor een factuur die aan een zakelijke koper is gericht, een factuur waarvan het lidmaatschap is opgezegd, en wanneer je credential geen payment:charge heeft. Een zakelijke koper is een klant die een ander Whop-account is in plaats van een persoon.2
Stel de URL van de gehoste checkout samen
Splits de link bij de eerste
.: het pay_-ID van de factuur staat ervoor en het token erachter.3
Stuur hem naar de klant
Verzend de factuur om Whop de link te laten mailen, of zet de URL in je eigen e-mail of factuurpagina. Alleen de klant van de factuur kan ermee betalen. Iedereen anders wordt geweigerd en gevraagd in te loggen als de klant van de factuur. De link werkt niet meer zodra de factuur is betaald, ongeldig gemaakt of als oninbaar gemarkeerd.
4
Lever uit vanuit de webhook
Luister naar
payment.succeeded voor het pay_-ID van de factuur, net als bij de automatische afschrijving. Webhooks toont een handler.Verzenden, inplannen en herinneren
Send Invoice mailt een factuur metPOST /invoices/{id}/send. Een concept verzenden geeft het eerst uit, net als Issue Invoice. Een open factuur verzenden mailt deze opnieuw.
open factuur heeft een checkout_link nodig om te worden verzonden, en een concept heeft een klant nodig die geen zakelijke koper is. Een concept dat aan een zakelijke koper is gericht, kan nog steeds worden verzonden als het een opgeslagen betaalmethode heeft, omdat het dan in plaats daarvan wordt afgeschreven.
Wie de e-mail ontvangt
Elke verzending mailt elk adres één keer, als aparte e-mail, zodat ontvangers elkaars adressen nooit zien. De adressen zijn:- Het e-mailadres van het Whop-account van de klant, dat de factuur-pdf onder Bill to afdrukt.
- Elk item in
recipient_emails.
recipient_emails op in kleine letters en ontdubbelt de lijst, dus een adres dat in beide voorkomt, krijgt één e-mail.
Een lege recipient_emails betekent dat Whop niemand mailt, ook de klant niet. Gebruik dit om te voorkomen dat Whop een factuur mailt:
- Send Invoice weigert de factuur, tenzij er in plaats daarvan een opgeslagen betaalmethode wordt belast.
- Er gaat geen betaallink uit na een geweigerde afschrijving.
- Er gaan geen herinneringen uit. Het leegmaken van
recipient_emailsop eenopenfactuur stopt de resterende herinneringen.
Wanneer Whop afschrijft in plaats van mailt
Een concept met eenpayment_method_id en een totaal boven nul wordt afgeschreven in plaats van gemaild, net als wanneer je het uitgeeft. Als de automatische afschrijving wordt geweigerd beschrijft wat er gebeurt als de afschrijving mislukt. Zo’n concept kan worden verzonden met een lege recipient_emails, omdat niemand de e-mail nodig heeft.
Verzendlimiet
Elke factuur kan drie keer per 24 uur worden gemaild, inclusief de verzending waarmee deze is uitgegeven. Een vierde verzending binnen die periode wordt geweigerd met een429 waarvan de error.code invoice_send_limit_reached is. Herinneringen, de betaallink na een geweigerde afschrijving en een verzending die afschrijft in plaats van mailt, tellen niet mee voor de limiet.
Een verzending inplannen
Om een concept later te verzenden, geef jesend_at mee. Het concept blijft een concept en toont het tijdstip in scheduled_send_at. Op dat moment verzendt Whop het alsof je toen Send Invoice had aangeroepen.
- Alleen een concept kan worden ingepland, en
send_atmoet in de toekomst liggen. Whop controleert de ontvangers en de betaallink bij het inplannen, net als bij direct verzenden. - Verzend opnieuw met een nieuwe
send_atom het tijdstip te verplaatsen. - Bewerken is vergrendeld totdat de verzending plaatsvindt of je deze annuleert. Een update die alleen
recipient_emailswijzigt, werkt nog steeds, maar kan niet de laatste ontvanger verwijderen van een concept dat niet wordt afgeschreven. - Cancel Scheduled Send met
POST /invoices/{id}/unschedule.scheduled_send_atwordt weernullen het concept kan weer worden bewerkt. Het annuleren voor een factuur zonder geplande verzending retourneert deze ongewijzigd. - Een ingepland concept ongeldig maken stopt de geplande verzending.
send_at uit. Als deze wordt geweigerd, bijvoorbeeld omdat een variant is verwijderd sinds je hem inplande, blijft de factuur een concept, wordt scheduled_send_at weer null en retourneert de API de reden niet. Elke andere fout wordt ongeveer elke 10 minuten opnieuw geprobeerd, tot in totaal 12 pogingen. Totdat een poging slaagt of Whop stopt met opnieuw proberen, toont scheduled_send_at het tijdstip van de volgende poging in plaats van null. Lees de factuur na send_at om te bevestigen dat deze open is.
Herinneringen
Wanneer Send Invoice een factuur met eendue_at mailt, plant Whop ook herinneringen in op 1, 3, 7, 14, 30 en 60 dagen na due_at, waarbij herinneringen waarvan de datum al voorbij is, worden overgeslagen. Elke herinnering gaat naar dezelfde adressen als de factuur en vermeldt hoeveel dagen de factuur over de vervaldatum is.
Herinneringen gaan alleen uit zolang de factuur open is, dus ze stoppen zodra de factuur is betaald, ongeldig gemaakt of als oninbaar gemarkeerd. Een herinnering die verschuldigd wordt terwijl een betaling bezig is, wacht tot de betaling is afgerond. Een factuur die je uitgeeft zonder te verzenden, of een die wordt afgeschreven in plaats van gemaild, krijgt geen herinneringen.
E-mailgeschiedenis
List Invoice Sends retourneert geregistreerde e-mailbatches metGET /invoices/{id}/sends, de nieuwste eerst. Dit omvat eerste en herhaalde e-mails, ingeplande e-mails, herinneringen en betalingsopvolgingen na een mislukte afschrijving van een opgeslagen betaalmethode. Gebruik het eerste item voor de meest recente geregistreerde verzending, en page_info.end_cursor als after om oudere items te lezen. Handmatige batches gebruiken send als de factuur geen eerdere voltooide e-mailgeschiedenis heeft, en anders resend. Het soort wordt gekozen wanneer de voltooide batch wordt geregistreerd, dus verzoeken die samen in de wachtrij staan, worden in volgorde van voltooiing ingedeeld. Eerdere niet-geregistreerde e-mails blijven onbekend.
Elk item bevat kind, sent_at, recipient_count, recipients en actor. Het lezen van de geschiedenis vereist payment:basic:read. Adressen vereisen ook member:email:read. Zonder die machtiging is recipients leeg. De afzender vereist ook company:authorized_user:read. Anders is actor null. Automatische verzendingen en account-API-sleutels hebben ook een null-actor.
De worker voegt een item toe nadat de hele batch ter bezorging is aangeboden. Voor een gedeeltelijke batch voegt hij alleen een item toe als een nieuwe poging de batch voltooit. Het item behoudt de oorspronkelijke ontvangerslijst. Een geregistreerde batch bevestigt geen bezorging in de inbox. De mailer kan berichten onderdrukken als de factuur of de ontvangers vóór de bezorging veranderen. De geschiedenis bevat geen e-mails die zijn verzonden voordat deze functie werd geïntroduceerd. Een factuur uitgeven zonder te mailen voegt geen item aan de geschiedenis toe.
Een pdf downloaden
Generate Invoice PDF bouwt de factuur als pdf en retourneert een kortlevende link ernaartoe. Het vereistpayment:basic:read en werkt bij elke status.
url en expires_at. De link werkt 15 minuten en iedereen die hem heeft, kan het bestand downloaden. Genereer een nieuwe wanneer hij verloopt.
De pdf begint met je bedrijf: de naam van je account staat bovenaan de pagina en de voettekst vermeldt dat Whop Inc de factuur op jouw naam en namens jou uitgeeft. De pdf toont het factuurnummer, de factuurdatum en vervaldatum, en de gegevens onder Bill to. Elk item toont de hoeveelheid, de eenheidsprijs en het bedrag, gevolgd door het subtotaal, de servicekosten, de belasting en het verschuldigde bedrag. Een factuur met een terugkerend item vermeldt ook het verlengingsbedrag en hoe vaak er wordt verlengd. De pdf van een concept toont de geschatte totalen, met belasting op nul totdat je het uitgeeft.
Sommige inhoud hangt af van de machtigingen van je credential:
Een abonnement factureren
Zet een terugkerende variant op een factuur om een abonnement te starten wanneer de klant deze betaalt. Whop verlengt het daarna één keer per factureringsperiode.- De factuur factureert de eerste periode en eventuele vooruitbetaalde kosten. Een terugkerend item moet bij een product horen en heeft een hoeveelheid van 1. Vanaf API-versie
2026-11-11factureert de eerste factuurinitial_priceplusrenewal_price. Betalen start direct de eerste betaalde factureringsperiode, tenzij de variant een gratis proefperiode heeft. Dan begint het abonnement met de proefperiode. In het dashboard heeft een aangepast terugkerend item een optioneel veld Upfront fee. Deinitial_pricevan het regelitem geeft dat eenmalige deel vanunit_amountaan, en de factuurpagina, de e-mail en de pdf vermelden het op een eigen regel Upfront fee. - Het betalen van de factuur start het abonnement, of Whop nu de opgeslagen betaalmethode bij uitgifte belast of de klant via de
checkout_linkbetaalt. De eerste periode begint bij de betaling. De checkout die vanuit de link wordt geopend, vermeldt het verlengingsbedrag, inclusief de kopersvergoeding van de factuur, en hoe vaak er wordt verlengd. - Elke verlenging wordt geïnd op de manier die je koos toen je de factuur uitgaf of verzond. Ze factureert alleen de terugkerende items, met de kopersvergoeding van de factuur, tegen de verlengingsprijs die elke variant had toen je de factuur uitgaf. Die kan afwijken van de prijs die op het concept is opgeslagen als de prijs van de variant is gewijzigd nadat je de items opsloeg. Eenmalige items worden één keer gefactureerd.
collection_method mee aan Issue Invoice of Send Invoice om te kiezen hoe verlengingen worden geïnd. Een geplande verzending past de collection_method toe waarmee je deze hebt ingepland, die het concept als scheduled_collection_method toont.
send_invoice vereist minstens één adres in recipient_emails en is niet beschikbaar voor facturen die aan een bedrijf zijn gericht. Zolang het van toepassing is, kan de laatste ontvanger van de factuur niet worden verwijderd. Een factuur zonder terugkerend item weigert collection_method. Het betalen van de eerste factuur met een kaart behoudt send_invoice.
Elke verlenging is een eigen betaling, met een eigen pay_-ID en eigen payment.*-webhooks. Een charge_automatically-verlenging is geen genummerde factuur, dus deze verschijnt niet in List Invoices. Een send_invoice-verlenging is een genummerde factuur in List Invoices, en Whop schrijft deze niet automatisch af. Het abonnement blijft past_due totdat de klant betaalt via de checkout_link van de factuur. De klant behoudt in de tussentijd toegang. Zeg het lidmaatschap op om verlengingen te stoppen. Zodra het lidmaatschap is opgezegd, werkt de checkout_link van een openstaande verlengingsfactuur niet meer.
Om het abonnement te vinden, haal je de factuur op als betaling en lees je de membership_id, waarvoor member:basic:read nodig is.
Beginnen met een gratis proefperiode
Een factuur respecteert detrial_period_days van een terugkerende variant, net als de checkout. De eerste factuur factureert alleen de initial_price van de variant. Het betalen ervan start de proefperiode, en de eerste verlenging factureert renewal_price wanneer de proefperiode eindigt. Facturen die vóór 2026-11-16 17:00 UTC zijn aangemaakt, factureren de eerste periode en slaan de proefperiode over.
- Een klant die al een abonnement op de variant had, krijgt geen proefperiode. De eerste factuur factureert
initial_priceplusrenewal_price. Verlengingsfacturen starten nooit een proefperiode. - De proefperiode komt van de variant. Stel voor een aangepast terugkerend item
variant.trial_period_daysin. Eentrial_period_daysop itemniveau wordt geweigerd. - Elk terugkerend item op de factuur heeft dezelfde lengte van de proefperiode nodig.
- Als de factuur niets in rekening brengt, geef je deze uit of verzend je deze met een
payment_method_id, waarmee de proefperiode direct start, of metcollection_method: "send_invoice". - In het dashboard heeft een aangepast terugkerend item een veld Free trial days. Het factureringsplan van een product toont zijn eigen proefperiode.
Stoppen na een vast aantal betalingen
Om een vast betalingsplan te factureren, zoals zes maandelijkse betalingen, stel jesplit_pay_required_payments in op de terugkerende variant, van 2 tot 115. De factuur is de eerste betaling, inclusief eventuele vooruitbetaalde kosten. Een vooruitbetaling van $75 met drie termijnen van $40 factureert bijvoorbeeld $115, dan $40 en dan $40. Whop stopt met verlengen zodra dat aantal betalingen is gedaan, en het lidmaatschap blijft actief. De klant kan het abonnement vóór die tijd niet zelf opzeggen, maar jij wel. Laat het leeg om te verlengen totdat het abonnement wordt opgezegd.
Statussen en levenscyclus
status neemt zijn waarden over van betalingen, dus een factuur kan ook een betalingsstatus tonen, zoals pending, terwijl een betaling bezig is. totals_status vertelt je of de geldvelden definitief zijn: estimated zolang de factuur een concept is, final nadat je deze hebt uitgegeven. overdue is true voor een open of uncollectible factuur waarvan de due_at is verstreken.
Ongeldig maken of als oninbaar markeren
Void Invoice annuleert een factuur met de statusdraft, open of uncollectible. Een factuur ongeldig maken die al ongeldig is, retourneert deze ongewijzigd, en een betaalde factuur kan niet ongeldig worden gemaakt.
Markeer een factuur als oninbaar om vast te leggen dat je niet verwacht deze te innen. Alleen een open factuur kan worden gemarkeerd, en een oninbare factuur opnieuw markeren retourneert deze ongewijzigd. Een oninbare factuur heeft geen checkout_link en krijgt geen herinneringen.
Dit voorbeeld markeert een open factuur als oninbaar en maakt deze daarna ongeldig:
Een factuur verwijderen
Delete Invoice verwijdert een factuur met de statusdraft of void met DELETE /invoices/{id}. Het antwoord is { id, deleted: true }. Een verwijderde factuur verschijnt niet meer in List Invoices of List Payments, en het ID ervan retourneert een 404. Je kunt een verwijdering niet ongedaan maken.
Maak een open factuur ongeldig voordat je deze verwijdert. Een concept met een geplande verzending of afschrijving heeft eerst Cancel Scheduled Send nodig. Een verlengingsfactuur in concept kan niet worden verwijderd zolang deze een abonnement factureert. Een ongeldige factuur die geld heeft geïnd of nog op een bankoverschrijving wacht, kan niet worden verwijderd, en een betaalde, lopende of oninbare factuur ook niet. Het veld deletable van een factuur is true als deze kan worden verwijderd.
Verwijderen vereist invoice:update of payment:charge. Het nummer van een verwijderd concept wordt niet hergebruikt.
Facturen weergeven en ophalen
List Invoices retourneert de facturen die je credential kan lezen, de nieuwste eerst. Een API-sleutel ziet het eigen account, en een gebruikerstoken ziet elk account waarvan de gebruiker betalingen kan lezen. Beperk de lijst met deze queryparameters:
Een ingepland concept is een concept met een
scheduled_send_at. Een open factuur is nooit ingepland, en een concept dat op de vervaldatum wordt verzonden ook niet.
Sorteer met order (created_at, due_at of scheduled_send_at) en direction (asc of desc). Sorteren op due_at of scheduled_send_at zet facturen zonder die datum achteraan. Het antwoord is { data, page_info }. Zolang page_info.has_next_page true is, geef je page_info.end_cursor mee als after om de volgende pagina te lezen.
pay_-ID. List Payments laat concepten weg.
Om facturen als csv-bestand te exporteren, roep je Create Export aan met resource: "receipt_invoices". Dit vereist payment:basic:read en payment:basic:export. De klantkolommen verschijnen alleen als je credential ook member:basic:read of member:email:read heeft.
Webhooks
Native facturen versturen betalingswebhooks voor hunpay_-ID. De invoice.*-events horen bij de legacy-factuur-API, en native facturen versturen ze niet.
Andere
payment.*-events, zoals payment.failed, kunnen ook binnenkomen voor het pay_-ID van de factuur wanneer de betalingspogingen veranderen. Abonneer je erop met de webhooksgids.
Om een bestelling uit te leveren, sla je het id van de factuur op bij de bestelling wanneer je het concept aanmaakt. De data van een payment.succeeded-event is de betaling, dus data.id is het pay_-ID van de factuur. Nadat je het event hebt geverifieerd, zoek je de bestelling op met dat ID. In deze handler staat orders voor je eigen bestellingenopslag:
fulfilled voorkomt dat een opnieuw bezorgd event de bestelling twee keer uitlevert. Abonnementsverlengingen hebben hun eigen pay_-ID’s, dus ze komen niet overeen met een factuur.
Betalingsregels bij factuurbetalingen
Je betalingsregels worden op factuurbetalingen uitgevoerd na de eigen fraudescreening van Whop, net als bij elke checkout. Wat ze kunnen doen, hangt af van of de klant aanwezig is.- De automatische afschrijving bij uitgifte is off-session. Een
block-regel weigert deze, en eenallow-regel stelt deze vrij van je andere regels.review- enenforce_3ds-regels worden overgeslagen omdat de afschrijving off-session is. - Een betaling via de checkoutlink is on-session. Alle vier de acties zijn van toepassing, met de geschiktheidslimieten uit Fraude beheren.
customer_email is het e-mailadres van het Whop-account van de klant. De payment_rule_matches van de betaling vermeldt de regel die de beslissing nam. Een overgeslagen regel wordt niet vermeld.
Facturen in het dashboard
De pagina Invoices toont, maakt en verzendt native facturen. Legacy-facturen staan op het tabblad Legacy invoices, dat wordt beschreven in Een factuur verzenden.Machtigingen
Elke schrijfbewerking vereist
payment:charge, dezelfde machtiging als Create Payment, en elke leesbewerking vereist payment:basic:read. De invoice:*-machtigingen horen bij de legacy-factuur-API, en native facturen gebruiken ze niet. Aanmaken of bijwerken met een inline plan-item vereist ook plan:create.
Sommige velden vereisen een eigen machtiging. Zonder die machtiging komt het veld terug als null, en recipient_emails komt leeg terug.
Als je credential na een
POST een van deze leesmachtigingen verliest, wordt het opnieuw afspelen met dezelfde Idempotency-Key geweigerd met een 403 waarvan de error.code invoice_replay_permission_revoked is, wanneer het opgeslagen antwoord die velden toont. Haal de factuur in plaats daarvan op met GET. Voeg machtigingen toe via de gids over machtigingen.
Fouten
Weigeringen komen terug als{ error: { type, message, code } }. Elke onderstaande code is een 400, tenzij anders vermeld. Een onbekende plan_id, member_id, mailing_address_id of payment_method_id is een 404, en een tijdstempel die Whop niet kan lezen, is een 400 met invalid_timestamp.
Deze weigeringen zijn een 400 zonder error.code, dus lees error.message voor de reden:
- Een onbekend veld op het hoogste niveau.
- Een
quantitybuiten 1 tot 999.999. - Een ongeldig adres in
recipient_emails, of meer dan 50 adressen. - Een overtreden regel voor meerdere items, zoals een verschil in factureringsperiode.
Fouten bij aanmaken en bijwerken
Fouten bij uitgeven
Fouten bij verzenden en inplannen
Een concept verzenden geeft het uit, dus een verzending kan ook worden geweigerd om elke reden uit Fouten bij uitgeven.Andere fouten
Het ongeldig maken van een betaalde factuur geeft een
400 zonder code.
Volgende stappen
API-referentie voor facturen
Elk factuur-endpoint, elke parameter en elk antwoordveld.
Betaalmethoden opslaan
Verzamel de opgeslagen betaalmethode die een factuur bij uitgifte belast.
Fraude beheren
Schrijf de betalingsregels die factuurbetalingen screenen.
Naar webhooks luisteren
Volg
payment.created en payment.succeeded voor je facturen.
