Skip to main content
Native facturen gebruiken dezelfde /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. Gebruik 4.99 voor 4,99 USD. Als je 499 stuurt, wordt 499 USD gefactureerd.
De native request maakt een concept aan. Verstuur het met 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-1 kun 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_address en customer_name zijn invoervelden die alleen bij create werken.
  • Uitgegeven bedragen en items zijn vergrendeld. Een update met alleen memo en/of recipient_emails is toegestaan op draft-, open- en uncollectible-facturen, inclusief een gepland concept.

Uitgeven, versturen en belasten

Een legacy-create kiest het incassogedrag met collection_method. Native facturen gebruiken aparte aanroepen na het aanmaken van het concept:
  1. Geef het uit met POST /invoices/{id}/issue om de definitieve belasting te berekenen en het open te stellen voor betaling zonder de eerste factuurmail te versturen.
  2. 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 een open-factuur verstuurt, wordt die opnieuw gemaild. send_at plant de verzending van een concept in. POST /invoices/{id}/unschedule annuleert die planning.
  3. Belast een opgeslagen betaalmethode door payment_method_id op het concept in te stellen. Bij een positief totaal belast uitgeven of versturen op een toekomstige charge_at, anders op een toekomstige due_at, en anders direct. charge_at moet in de toekomst liggen en mag niet vóór send_at liggen.
Als je een concept verstuurt dat direct belast, wordt de eerste factuurmail overgeslagen. Als je verstuurt met een latere charge, wordt de mail nu verstuurd. Een mislukte automatische charge kan een e-mail met een betaallink activeren, ook wanneer je Issue Invoice hebt gebruikt. Een opgeslagen betaalmethode belasten legt de flow uit. Een 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 hun pay_-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

  1. Controleer Voordat je migreert op workflows die op de legacy-API moeten blijven.
  2. Zet native aanroepen vast op een uitgebrachte versie die overeenkomt met hun veldnamen, zoals 2026-11-02-1 voor deze voorbeelden.
  3. Bouw items op uit geschikte varianten en controleer hoeveelheden, prijzen, valuta en productvereisten.
  4. 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.
  5. Koppel vervaldatums, geplande verzendingen en kopersvergoedingen op basis van hun gedrag, niet alleen op basis van hun veldnamen.
  6. Houd native pay_-ID’s en legacy inv_-ID’s gescheiden. Houd legacy-reads op de eerdere versie.
  7. Lees bedragen uit geldobjecten en open de checkout met de ondertekende checkout_link.
  8. Handel overdue en de extra betalingsstatussen af.
  9. Lever op basis van payment.succeeded voor de betalings-ID van de factuur.
  10. 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.