/invoices-paden als legacy-facturen, maar hebben een ander requestformaat en een andere levenscyclus. Deze handleiding koppelt de velden en acties die je moet wijzigen wanneer je een integratie migreert.
De gedeelde paden leiden vanaf
Api-Version-Date: 2026-10-24 naar native facturen.
De native voorbeelden hieronder gebruiken Api-Version-Date: 2026-11-02-1, met de
huidige veldnamen voor varianten en de regels voor het vastzetten van klanten. Stuur die header mee
bij elke native request. Houd legacy-aanroepen op een eerder uitgebrachte versie, zoals
2026-10-15-1. API-versies legt uit hoe headers
vastgezette versies van credentials overschrijven.Wat er verandert
De native API kan legacy
inv_-facturen niet weergeven of ophalen. Blijf bestaande legacy-facturen lezen met de eerdere API-versie. Een native factuur aanmaken maakt een aparte rekening aan. Het converteert of vereffent geen legacy-factuur.
Voordat je migreert
Controleer deze verschillen voordat je een flow overzet. Houd de flow op de legacy-API als die een functie nodig heeft die de native API niet biedt.De create-request koppelen
Een legacy-create stuurt één plan en eventueel labels die de prijs ervan opsplitsen. Een native create stuurt een item voor elke gefactureerde variant. Deze voorbeelden stellen een gecombineerde itemprijs van 19,99 USD in. De bestaande native variant vertegenwoordigt de installatiekosten van 15 USD. De servicekosten van 4,99 USD zijn een aangepaste eenmalige charge zonder product. Beide API’s accepteren prijzen in valuta-eenheden. Gebruik4.99 voor 4,99 USD. Als je 499 stuurt, wordt 499 USD gefactureerd.
POST /invoices/{id}/send om het uit te geven en te e-mailen. member_id identificeert een klant (mber_), geen abonnement (mem_).
Gebruik voor native versies vóór
2026-10-27-2 plan_id, plan en plan_type in plaats van variant_id, variant en billing_type. De regelitems in de response gebruiken in die oudere versies ook plan_id.
Uitgegeven bedragen vergrendeld houden
PATCH /invoices/{id} bewerkt de items en factureringsgegevens van een concept. Als je items meestuurt, wordt de hele lijst vervangen op basis van de huidige prijzen van de varianten. Als je het weglaat, blijven de opgeslagen items en prijzen behouden.
- Annuleer een geplande verzending voordat je items of factureringsgegevens bewerkt.
- Vanaf
2026-11-02-1kun je de toegewezen klant van een concept niet vervangen of wissen. Een concept zonder klant kan er nog wel een krijgen. Maak het concept ongeldig voordat je een nieuwe factuur voor iemand anders aanmaakt. email_addressencustomer_namezijn invoervelden die alleen bij create werken.- Uitgegeven bedragen en items zijn vergrendeld. Een update met alleen
memoen/ofrecipient_emailsis toegestaan opdraft-,open- enuncollectible-facturen, inclusief een gepland concept.
Uitgeven, versturen en belasten
Een legacy-create kiest het incassogedrag metcollection_method. Native facturen gebruiken aparte aanroepen na het aanmaken van het concept:
- Geef het uit met
POST /invoices/{id}/issueom de definitieve belasting te berekenen en het open te stellen voor betaling zonder de eerste factuurmail te versturen. - Of verstuur het met
POST /invoices/{id}/send. Dit geeft het concept uit. Het e-mailt de ontvangers, tenzij er direct een opgeslagen betaalmethode wordt belast. Als je eenopen-factuur verstuurt, wordt die opnieuw gemaild.send_atplant de verzending van een concept in.POST /invoices/{id}/unscheduleannuleert die planning. - Belast een opgeslagen betaalmethode door
payment_method_idop het concept in te stellen. Bij een positief totaal belast uitgeven of versturen op een toekomstigecharge_at, anders op een toekomstigedue_at, en anders direct.charge_atmoet in de toekomst liggen en mag niet vóórsend_atliggen.
open-response bevestigt geen betaling. Wacht op payment.succeeded voordat je levert. Gebruik Charge Invoice om een openstaande factuur te belasten of opnieuw te proberen. Opnieuw uitgeven of versturen start geen nieuwe charge.
Voor een terugkerende variant bepaalt collection_method op Issue Invoice of Send Invoice de verlengingen. charge_automatically int toekomstige betalingen automatisch. send_invoice maakt elke periode een nieuwe factuur aan en e-mailt die. Het vervangt payment_method_id niet voor het innen van de eerste factuur. Zie Een abonnement factureren.
De response koppelen
Roep
POST /invoices/{id}/generate_pdf aan om een kortlevende link te krijgen waarmee je een pdf downloadt.
De factuurcheckout openen
checkout_link bevat de factuur-ID en een ondertekend token, gescheiden door een .. Geef de volledige waarde als link door aan POST /checkout_sessions om een sessie voor deze factuur te openen. Volg De gehoste checkout-URL opbouwen voor een URL voor klanten.
Het veld is alleen aanwezig zolang de checkout beschikbaar is: de factuur moet open zijn. Zakelijke kopers en opgezegde lidmaatschappen kunnen deze checkout niet gebruiken. Je sleutel heeft payment:charge nodig, of invoice:create/invoice:update wanneer de factuur geen opgeslagen betaalmethode heeft. Het is null bij een concept, een betaalde, ongeldige of oninbare factuur, en voor zakelijke kopers.
Statussen koppelen
Native facturen kunnen ook
authorized, pending of unresolved teruggeven. Behandel niet elke status buiten de legacy-enum als betaald of mislukt. Statussen en levenscyclus legt ze uit.
Endpoints koppelen
Webhooks koppelen
Native facturen versturen betalingsevents voor hunpay_-ID. De invoice.*-events beschrijven legacy-facturen.
Betalingsevents dekken ook betalingen die niets met facturen te maken hebben. Koppel de betalings-ID van het event aan de native factuur-ID’s die je opslaat. Webhooks laat zien hoe je levert op basis van
payment.succeeded.
Machtigingen
member:basic:read geeft toegang tot klantnamen en member-/lidmaatschaps-ID’s. member:email:read geeft toegang tot email_address en recipient_emails. Velden voor betaalmethoden en adressen vereisen payment:basic:read.
Migratiechecklist
- Controleer Voordat je migreert op workflows die op de legacy-API moeten blijven.
- Zet native aanroepen vast op een uitgebrachte versie die overeenkomt met hun veldnamen, zoals
2026-11-02-1voor deze voorbeelden. - Bouw
itemsop uit geschikte varianten en controleer hoeveelheden, prijzen, valuta en productvereisten. - Vervang de legacy-create in één aanroep door create, gevolgd door uitgeven of versturen. Kies charges op een opgeslagen betaalmethode voor de eerste factuur en een incassomethode voor verlengingen.
- Koppel vervaldatums, geplande verzendingen en kopersvergoedingen op basis van hun gedrag, niet alleen op basis van hun veldnamen.
- Houd native
pay_-ID’s en legacyinv_-ID’s gescheiden. Houd legacy-reads op de eerdere versie. - Lees bedragen uit geldobjecten en open de checkout met de ondertekende
checkout_link. - Handel
overdueen de extra betalingsstatussen af. - Lever op basis van
payment.succeededvoor de betalings-ID van de factuur. - Verleen de machtigingen die je flow gebruikt, inclusief de machtigingen voor inline varianten/producten en het lezen van klantgegevens.
Volgende stappen
Handleiding voor facturen
Native facturen aanmaken, uitgeven, versturen en innen.
API-referentie voor facturen
Elk native factuur-endpoint en -veld.
Legacy-factuur-API
De endpoints die je huidige integratie aanroept.
API-versies
Hoe
Api-Version-Date en vastgezette versies werken.
