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…",
      "productId": "jh7…",
      "productName": "Jaarlidmaatschap",
      "priceId": "kn7…",
      "priceSku": "JAAR-01",
      "priceLabel": "Per jaar",
      "amountCents": 29900,
      "currency": "EUR",
      "vatPercentage": 21,
      "interval": "1 year",
      "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.
productId string Het product, zoals in het producten-endpoint.
productName string of null Naam van het product op het moment van afsluiten.
priceId string De prijs, zoals in het prijzen-endpoint.
priceSku string of null Eigen artikelcode van de prijs, zoals die nu is ingesteld. Handig als koppelsleutel naar je boekhouding of een ander systeem.
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, in de notatie van Mollie: 1 month, 3 months, 1 year of N months.
priceType string Soort prijs waarop dit abonnement loopt.
status string active, trialing, past_due, pending_activation, paused, 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.
Welke waarden kan interval hebben?
De notatie van Mollie: 1 month, 3 months of 1 year, en bij een meerjarige cadans het aantal maanden, zoals 24 months. Wil je ermee rekenen, gebruik dan intervalMonths uit het prijzen-endpoint.
Hoe koppel ik een abonnement aan een artikel in mijn boekhouding?
Geef de prijs in Memly een SKU, dezelfde code als in je boekhouding. Die komt hier terug als priceSku. Het is de code die nu op de prijs staat, dus pas je hem aan, dan zie je bij elk abonnement op die prijs de nieuwe code.
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.