Naar hoofdinhoud

Facturen

GET https://scintillating-wolf-799.eu-west-1.convex.site/v1/invoices

Facturen met bedragen, btw en betaalmoment. Bedragen zijn centen; het subtotaal is exclusief btw, het totaal inclusief.

Rechten: finance:read. Deze gegevens gaan over personen.

Facturen zijn de plek waar je ziet wat er daadwerkelijk betaald is. Een abonnement zegt wat er zou moeten binnenkomen, een factuur met status paid zegt wat er binnen is, en dat verschil is precies waar een omzetoverzicht op moet leunen.

Het subtotaal is exclusief btw en het totaal inclusief. Voor een omzetrapportage gebruik je subtotalAmountCents, want dat is het deel dat van jou is; het verschil met totalAmountCents draag je af.

Een creditfactuur heeft type credit en draait een eerdere factuur terug. Tel je alle facturen bij elkaar op zonder op dit veld te letten, dan tel je terugbetalingen als omzet mee. Filter op type of trek de creditbedragen af.

De parameter since filtert op betaaldatum en werkt daarom alleen samen met status=paid. Bij een andere status zou hij stilzwijgend alles wegfilteren, en een lege lijst die niets over de werkelijkheid zegt is het vervelendste antwoord dat een API kan geven. Daarom is die combinatie een fout.

Parameters

Naam Uitleg
status draft, issued, paid (standaard), overdue of credited.
since Epoch-milliseconden. Filtert op betaaldatum en werkt daarom alleen samen met status=paid.
limit Aantal items per pagina, 1 tot en met 500. Standaard 100. Een waarde daarbuiten geeft een fout in plaats van een stille correctie.
cursor De nextCursor uit het vorige antwoord. Blijf doorbladeren tot nextCursor null is, ook als een pagina niet vol zit.

Voorbeeld

curl "https://scintillating-wolf-799.eu-west-1.convex.site/v1/invoices" \
  -H "Authorization: Bearer <je sleutel>"

Antwoord

{
  "items": [
    {
      "id": "kn2…",
      "invoiceNumber": "B2026-000000412",
      "status": "paid",
      "type": "invoice",
      "paidAt": 1767312000000,
      "subtotalAmountCents": 24711,
      "totalAmountCents": 29900,
      "vatPercentage": 21,
      "currency": "EUR",
      "subscriptionId": "ks7…",
      "subscriptionProductName": "Jaarlidmaatschap"
    }
  ],
  "nextCursor": null
}

Velden

Veld Type Betekenis
id string Vaste verwijzing naar deze factuur.
invoiceNumber string Het factuurnummer zoals de klant het ziet.
status string draft, issued, paid, overdue of credited.
type string invoice of credit. Een creditfactuur draait een eerdere terug.
paidAt getal of null Wanneer er betaald is.
subtotalAmountCents getal Bedrag exclusief btw, in centen.
totalAmountCents getal Bedrag inclusief btw, in centen. Dit is wat er geïncasseerd wordt.
vatPercentage getal Btw-percentage op deze factuur.
currency string Munteenheid, in de praktijk EUR.
subscriptionId string of null Het abonnement waar deze factuur bij hoort. Null bij een losse aankoop.
subscriptionProductName string of null Productnaam van dat abonnement, om omzet aan een stroom toe te wijzen.

Veelgestelde vragen

Hoe haal ik alleen de omzet van deze maand op?
Gebruik status=paid met since op het begin van de maand in epoch-milliseconden. Tel daarna subtotalAmountCents op voor het bedrag exclusief btw.
Waarom heeft een factuur geen subscriptionId?
Dan hoort hij bij een eenmalige aankoop en niet bij een abonnement. Beide soorten staan door elkaar in dezelfde lijst.
Wat betekent status overdue?
De factuur staat open en is te laat. Die facturen zie je met meer context in de openstaande facturen, inclusief waar ze in de herinneringscyclus staan.

Hierna nodig

Werkt je aanroep niet zoals verwacht, kijk dan bij de foutcodes en wat ze betekenen. Heb je nog geen sleutel, dan legt de kennisbank uit hoe je er een aanmaakt.