Naar hoofdinhoud

Bestellingen

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

Bestellingen met de producten erin en de gegevens van de koper. Bedragen zijn centen, inclusief btw.

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

Dit is het endpoint waar een koppeling de details ophaalt na een webhook. De webhook zegt dát er iets gebeurd is; hier staat wat er op dit moment van waar is. Wie beide gebruikt, hoeft nooit op de inhoud van een bericht te vertrouwen.

Geef id mee om één bestelling op te halen; de overige parameters vervallen dan. Zonder id krijg je de lijst met de nieuwste bestelling bovenaan, en betaal je met cursor door naar de volgende pagina.

Een bestelling kan meer dan één product bevatten (items). Kijk daar dus naar, en niet alleen naar het eerste product.

isTrial betekent dat dit een proefperiode is met een verificatiebedrag. Wie daar een klant van maakt, maakt hem aan voordat er echt betaald is.

Testbestellingen blijven buiten dit endpoint, net als bij de facturen. Een bestelling die in de testmodus van een betaalpagina is gemaakt, telt nergens mee en komt hier dus ook niet voorbij.

Parameters

Naam Uitleg
id Eén bestelling ophalen. De overige parameters vervallen dan.
status pending, paid, failed, expired of cancelled. Standaard paid.
since Epoch-milliseconden. Filtert op betaalmoment en werkt 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/orders" \
  -H "Authorization: Bearer <je sleutel>"

Antwoord

{
  "items": [
    {
      "id": "j57…",
      "orderNumber": "B2026-000000618",
      "status": "paid",
      "paidAt": 1789056000000,
      "isTrial": false,
      "totalAmountCents": 29900,
      "currency": "EUR",
      "items": [
        {
          "productId": "nx7…",
          "productName": "SEO Check",
          "priceId": "kp2…",
          "isRecurring": false
        }
      ],
      "customer": {
        "userId": null,
        "email": "arthur@voorbeeld.test",
        "firstName": "Arthur",
        "lastName": "Dekker",
        "companyName": "Dekker Tuning Service"
      }
    }
  ],
  "nextCursor": null
}

Velden

Veld Type Betekenis
id string Vaste verwijzing naar deze bestelling.
orderNumber string Het bestelnummer zoals de klant het ziet.
status string pending, paid, failed, expired of cancelled.
paidAt getal of null Wanneer er betaald is.
isTrial boolean Een proefperiode met verificatiebedrag, nog geen echte betaling.
totalAmountCents getal Bedrag inclusief btw, in centen.
currency string Munteenheid, in de praktijk EUR.
items lijst De producten in deze bestelling: productId, productName, priceId en isRecurring.
customer object userId (kan null zijn bij een nieuwe koper), email, firstName, lastName en companyName.

Veelgestelde vragen

Ik krijg een webhook binnen. Hoe weet ik zeker dat de bestelling echt betaald is?
Haal de bestelling op met id en kijk naar status. Dat is de stand van nu; een bericht is de stand van het moment van versturen.
Waarom staat er geen adres of btw-nummer in?
Alleen wat een koppeling nodig heeft om een klant te herkennen: naam, e-mailadres en bedrijfsnaam. De rest staat op de factuur.
Hoe haal ik de bestellingen op die ik gemist heb?
Gebruik since met een tijdstip in epoch-milliseconden. Handig na een storing of bij het inrichten van een koppeling die er nog niet was.

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.