Skip to main content
Een factuur is een genummerde rekening voor een of meer van je varianten, gericht aan één klant. Een variant is een prijs- en factureringsinstelling die je verkoopt, meestal voor een product. Het ID begint met 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 met pay_ 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.
  1. Je maakt een concept met items, een klant en factuurgegevens. Een concept brengt niets in rekening en mailt niemand.
  2. 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.
  3. 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.
  4. Je levert de bestelling uit vanuit de webhook payment.succeeded.
Facturen factureren buy-now-varianten, die met 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.
Stuur bij elke 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 met POST /invoices.
Het antwoord is 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 quantity voor 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.
  • quantity ligt 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.
Elk regelitem in het antwoord heeft een 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 met PATCH /invoices/{id}. Stuur alleen de velden die je wijzigt.
  • items vervangt 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_id verwijdert het opgeslagen factuuradres en de opgeslagen betaalmethode, tenzij je nieuwe meestuurt. recipient_emails blijft behouden, dus stuur ook een nieuwe lijst mee, anders ontvangt de vorige klant nog steeds de factuurmail.
  • email_address en customer_name worden niet geaccepteerd. Stuur een andere member_id om iemand anders te factureren.
  • Een concept met een geplande verzending accepteert alleen een wijziging van recipient_emails totdat 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 factuur open of uncollectible is. Elke andere bewerking wordt geweigerd met een 400.

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 met payment_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:
  1. Voert dezelfde controles uit die Create Payment uitvoert op een opgeslagen betaalmethode.
  2. Reserveert voorraad voor de gefactureerde hoeveelheden en bereidt de vergoedingen van de betaling voor.
  3. Retourneert de factuur als open en belast de methode off-session. De afschrijving vindt plaats op de charge_at die je aan Issue Invoice of Send Invoice meegeeft, anders op due_at zolang die nog in de toekomst ligt, en anders direct. scheduled_charge_at toont een afschrijving die nog moet plaatsvinden.
Het antwoord vertelt je niet of de afschrijving is geslaagd. Lever uit vanuit de 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 factuur open 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.
Een off-session afschrijving kan de klant geen 3D Secure-verificatie tonen. Als de bank erom vraagt, wordt de automatische afschrijving niet voltooid en blijft de factuur onbetaald totdat de klant zich verifieert of op een andere manier betaalt.

De factuur uitgeven

Issue Invoice maakt van een concept een open factuur. Whop controleert de factuur opnieuw, berekent de definitieve belasting en zet status 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_amount is null bij een concept en wordt ingesteld zodra je het uitgeeft. total en amount_due bevatten 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.created wordt één keer geactiveerd voor het pay_-ID van de factuur.
  • Opnieuw uitgeven is veilig. Een factuur uitgeven die al open is, 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.
Een geweigerde uitgifte wijzigt niets en schrijft niets af. Los de oorzaak op en geef de factuur opnieuw uit. Fouten bij uitgeven somt de redenen op. Een uitgegeven factuur met de status open 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.
De checkout toont het factuurnummer en de vervaldatum naast de items, en de vervaldatum wordt rood zodra deze is verstreken. De klant betaalt de items en het totaal op de factuur en kan geen promotiecode toevoegen.

Verzenden, inplannen en herinneren

Send Invoice mailt een factuur met POST /invoices/{id}/send. Een concept verzenden geeft het eerst uit, net als Issue Invoice. Een open factuur verzenden mailt deze opnieuw.
De e-mail toont de naam en het logo van je account, het factuurnummer, het totaal, de vervaldatum, elk item en een knop die de checkout van de factuur opent. Whop mailt alleen een factuur die de klant vanuit de e-mail kan betalen. Een 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.
Whop slaat 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_emails op een open factuur stopt de resterende herinneringen.

Wanneer Whop afschrijft in plaats van mailt

Een concept met een payment_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 een 429 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 je send_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_at moet 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_at om het tijdstip te verplaatsen.
  • Bewerken is vergrendeld totdat de verzending plaatsvindt of je deze annuleert. Een update die alleen recipient_emails wijzigt, 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_at wordt weer null en 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.
Whop controleert elke minuut op verzendingen die aan de beurt zijn, dus een geplande verzending gaat binnen ongeveer een minuut na 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 een due_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 met GET /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 vereist payment:basic:read en werkt bij elke status.
Het antwoord bevat 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.
  1. 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-11 factureert de eerste factuur initial_price plus renewal_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. De initial_price van het regelitem geeft dat eenmalige deel van unit_amount aan, en de factuurpagina, de e-mail en de pdf vermelden het op een eigen regel Upfront fee.
  2. Het betalen van de factuur start het abonnement, of Whop nu de opgeslagen betaalmethode bij uitgifte belast of de klant via de checkout_link betaalt. 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.
  3. 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.
Geef 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 de trial_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_price plus renewal_price. Verlengingsfacturen starten nooit een proefperiode.
  • De proefperiode komt van de variant. Stel voor een aangepast terugkerend item variant.trial_period_days in. Een trial_period_days op 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 met collection_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 je split_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 status draft, 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 status draft 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.
Retrieve Invoice leest één factuur op basis van het 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 hun pay_-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:
Het controleren van 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 een allow-regel stelt deze vrij van je andere regels. review- en enforce_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.
Bij de automatische afschrijving lezen kaartvoorwaarden de opgeslagen betaalmethode en factuurvoorwaarden het factuuradres van de factuur. 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 quantity buiten 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.