Naar hoofdinhoud

Abonnementen

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

Lopende en beëindigde abonnementen, met bedrag, cadans, status en de eerstvolgende incassodatum.

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

Dit endpoint geeft de terugkerende omzet van een omgeving. Elk abonnement staat er met zijn bedrag, cadans, status en de eerstvolgende incassodatum, dus je kunt er een omzetprognose op bouwen zonder de facturen te hoeven optellen.

De statussen active, trialing en past_due leveren nog geld op. Daarnaast bestaan pending_activation, cancelled, completed en paused. Standaard krijg je alleen die eerste drie; wil je ook de rest zien, bijvoorbeeld om verloop te berekenen, gebruik dan status=all.

Bij een opzegging gaat de status meteen naar cancelled en worden cancelledAt en expiresAt gezet. De toegang loopt daarna nog door tot expiresAt. Vraag je alleen status=active op, dan mis je dus abonnementen waarvan het lid vandaag nog gewoon toegang heeft.

Bedragen staan in centen en zijn inclusief btw, want dat is het bedrag dat daadwerkelijk wordt geïncasseerd. Wil je het bedrag exclusief btw, reken dat dan terug met vatPercentage, of gebruik de facturen, want die geven het subtotaal apart.

Parameters

Naam Uitleg
status active (standaard) geeft alleen abonnementen die nog geld opleveren; all geeft ook opgezegde en afgelopen.
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/subscriptions" \
  -H "Authorization: Bearer <je sleutel>"

Antwoord

{
  "items": [
    {
      "id": "ks7…",
      "userId": "qd7…",
      "productName": "Jaarlidmaatschap",
      "priceLabel": "Per jaar",
      "amountCents": 29900,
      "currency": "EUR",
      "vatPercentage": 21,
      "interval": "yearly",
      "priceType": "yearly",
      "status": "active",
      "startDate": 1767225600000,
      "nextPaymentDate": 1798761600000,
      "cancelledAt": null,
      "cancellationReason": null,
      "expiresAt": null,
      "completedAt": null,
      "trialEndsAt": null,
      "isTrial": false,
      "installmentCount": null,
      "installmentsPaid": null
    }
  ],
  "nextCursor": null
}

Velden

Veld Type Betekenis
id string Vaste verwijzing naar dit abonnement.
userId string Het lid dat het abonnement heeft.
productName string of null Naam van het product op het moment van afsluiten.
priceLabel string of null Label van de prijs. Ontbreekt die op het abonnement, dan komt hij uit de prijs zelf.
amountCents getal Bedrag per incasso in centen, inclusief btw.
currency string Munteenheid, in de praktijk EUR.
vatPercentage getal Btw-percentage over dit bedrag.
interval string Hoe vaak er geïncasseerd wordt, bijvoorbeeld monthly of yearly.
priceType string Soort prijs waarop dit abonnement loopt.
status string active, trialing, past_due, cancelled of completed. De eerste drie leveren nog geld op.
startDate getal Startmoment in epoch-milliseconden.
nextPaymentDate getal of null Eerstvolgende incasso. Null bij een abonnement dat niet meer loopt.
cancelledAt getal of null Moment van opzeggen. Toegang kan daarna nog doorlopen tot expiresAt.
cancellationReason string of null Reden die het lid koos bij het opzeggen.
expiresAt getal of null Tot wanneer de toegang geldt.
completedAt getal of null Moment waarop een reeks termijnen is uitbetaald.
trialEndsAt getal of null Einde van de proefperiode.
isTrial boolean Loopt dit abonnement nog in de proefperiode.
installmentCount getal of null Aantal termijnen bij een gespreide betaling.
installmentsPaid getal of null Hoeveel termijnen daarvan betaald zijn.

Veelgestelde vragen

Hoe zie ik of een abonnement is opgezegd?
Aan cancelledAt, en de status staat dan meteen op cancelled. Tot wanneer het lid nog toegang houdt staat in expiresAt.
Waarom klopt interval niet bij een tweejarig abonnement?
Gebruik intervalMonths uit het prijzen-endpoint. Het veld interval kent alleen de gangbare cadansen, terwijl intervalMonths ook 24 of 36 kan zijn.
Krijg ik hier ook eenmalige aankopen?
Nee, alleen abonnementen. Losse aankopen zie je terug bij de facturen, die een subscriptionId van null hebben.

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.