Borkol Docs startpagina

Bestellingen & offertes

Bestellingen

Een enkele bestelling ophalen, de bestelgeschiedenis van een klant opvragen, en de statusmachine van bestellingen.

Bekijk als Markdown

Een bestelling wordt aangemaakt door de checkout (of door het accepteren van een offerte) in status pending_payment. Vanuit de storefront API zijn bestellingen read-only: alle statuswijzigingen (betaling, verzending, terugbetalingen) gebeuren aan merchant-zijde in het dashboard. Beide endpoints vereisen de commerce:read scope en de commerce-module.

Bestelstatus

StatusBetekenisKan overgaan naar
pending_paymentAangemaakt, wacht op betaling.paid, cancelled
paidBetaling ontvangen.shipped, cancelled, refunded
shippedOvergedragen aan de vervoerder; trackingvelden kunnen gezet zijn.completed, refunded
completedAfgehandeld.refunded
cancelledGeannuleerd vóór afhandeling. De voorraad wordt teruggeboekt.terminaal
refundedTerugbetaald. De voorraad wordt teruggeboekt.terminaal

Behandel de enum als open: een client moet een onbekende toekomstige status neutraal weergeven in plaats van te falen.

De vorm van de bestelrespons

Beide endpoints serialiseren bestellingen identiek (enkele bestellingen verpakt in {"data": {...}}, geschiedenisitems als elementen van een gepagineerde data-array). Alle geldbedragen zijn objecten {"amount": int, "currency": "EUR"} met amount in minor units. Datums zijn ISO-8601-strings.

NaamTypeVerplichtBeschrijving
idstring (UUID)altijdBestelling-id.
numberintegeraltijdKlantgericht bestelnummer uit een teller per winkel. Gewone integer, geen UUID.
statusstringaltijdZie de statustabel hierboven.
emailstringaltijdHet e-mailadres opgegeven bij de checkout.
billing_addressobjectaltijdHet factuuradres zoals ingediend (name, street, postal_code, city, country).
shipping_addressobject of nullaltijdHet verzendadres, of null wanneer verzonden wordt naar het factuuradres.
currencystringaltijdEUR.
linesarrayaltijdBestelregels, zie hieronder.
subtotalmoneyaltijdGoederentotaal exclusief btw.
tax_totalmoneyaltijdTotale btw inclusief btw op verzending.
totalmoneyaltijdEindtotaal inclusief verzending.
tax_breakdownarrayaltijdUitsplitsing per tarief, elk {"rate": float, "base": int, "tax": int}.
discount_totalmoneyaltijdTotale goederenkorting toegepast bij checkout, exclusief een eventuele gratis-verzendkorting. amount is 0 wanneer geen korting is toegepast.
discount_breakdownarray of nullaltijdEén item per toegepaste korting, elk {"discount_id": uuid, "name": string, "code": string of null, "kind": "order" / "products" / "bogo" / "shipping", "amount": int}. Null wanneer geen korting is toegepast. Bij een shipping-item is amount de verzendkosten die zijn kwijtgescholden.
shipping_method_namestring of nullaltijdNaam-snapshot van de gekozen verzendmethode, null wanneer geen verzending is toegepast.
shippingmoneyaltijdVerzendkosten exclusief btw. amount is null wanneer geen verzending is toegepast.
shipping_taxmoneyaltijdBtw op verzending. amount is null wanneer geen verzending is toegepast.
tracking_carrierstring of nullaltijdGezet door de merchant bij verzending.
tracking_numberstring of nullaltijdGezet door de merchant bij verzending.
invoice_numberinteger of nullaltijdFactuurteller per winkel, gezet wanneer de merchant de bestelling factureert.
invoiced_atstring (ISO-8601) of nullaltijdWanneer de bestelling is gefactureerd.
customer_idstring (UUID) of nullaltijdHet contact waaraan de bestelling gekoppeld is, null voor gastbestellingen.
contact_idstring (UUID) of nullaltijdDezelfde waarde als customer_id; de canonieke naam vanaf nu.
placed_atstring (ISO-8601) of nullaltijdWanneer de bestelling is geplaatst.
created_atstring (ISO-8601) of nullaltijdAanmaaktijd van de rij.
invoice_idstring (UUID) of nullaltijdDe sales-factuur die uit deze order is aangemaakt, indien aanwezig. Null wanneer er geen factuur is of de winkel de sales-module niet gebruikt.

lines[]

NaamTypeVerplichtBeschrijving
idstring (UUID)altijdBestelregel-id.
product_idstring (UUID)altijdHet product.
variant_idstring (UUID) of nullaltijdDe variant, indien van toepassing.
variant_labelstring of nullaltijdLeesbaar variantlabel-snapshot, bijvoorbeeld "Green / M".
namestringaltijdProductnaam-snapshot.
skustring of nullaltijdSKU-snapshot.
quantitynumberaltijdBestelde hoeveelheid: een geheel getal voor een piece-product, tot drie decimalen voor elke andere eenheid (bijvoorbeeld 0.75).
unitstringaltijdDe eenheid van het product op het moment van de order: piece, kg, g, l, m, m2, m3 of hour.
unit_pricemoneyaltijdStukprijs.
line_subtotalmoneyaltijdRegeltotaal exclusief btw.
tax_ratenumberaltijdBtw-percentage toegepast op de regel.
taxmoneyaltijdBtw op de regel.
line_totalmoneyaltijdRegeltotaal inclusief btw.
attributesobject of nullaltijdRegelsnapshot vastgelegd bij het plaatsen van de order, zie hieronder.

lines[].attributes

NaamTypeVerplichtBeschrijving
returnablebooleanconditioneelOf de regel geretourneerd kan worden. Altijd false voor een made_to_measure-product; anders de returnable van het product op het moment van de order. Een regel zonder product (een eigen offerteregel, of een product dat is verwijderd voordat de offerte werd geaccepteerd) is true, met lead_time_days null.
lead_time_daysinteger of nullconditioneelDe levertijd van het product in dagen op het moment van de order, null wanneer die er niet was.
configurationobjectconditioneelAlleen made-to-measure-regels: de configuratiesnapshot (dimensions, choices, breakdown, components, matrix), zoals op de cartregel. components[].qty is een exacte decimale string.

returnable en lead_time_days worden vanaf 2026-10-11 vastgelegd op elke regel van orders die via de checkout, een handmatige order van de merchant of een geaccepteerde offerte zijn geplaatst. Eerdere orders kunnen attributes null hebben of zonder deze keys: behandel een ontbrekende waarde als onbekend.

GET /v1/api/commerce/orders/{id}

Haalt een enkele bestelling met regels op via id. Er is geen controle op klant-eigenaarschap op dit endpoint: het wordt puur geautoriseerd door de tenant-API-key, wat een server-side secret is. Het bestaat voor de storefront-server, bijvoorbeeld voor het renderen van de orderbevestigingspagina direct na de checkout. Proxy het nooit naar browsers met een door de client aangeleverd bestelling-id, tenzij je server eerst zelf een eigenaarschapscontrole uitvoert.

Parameters

Pad

NaamTypeVerplichtBeschrijving
idstring (UUID)jaBestelling-id.
Request
curl https://api.borkol.com/v1/api/commerce/orders/7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1 \
  -H "Authorization: Bearer {api_key}"
Response
{
  "data": {
    "id": "7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1",
    "number": 1042,
    "status": "paid",
    "email": "jane@example.com",
    "billing_address": {
      "name": "Jane Doe",
      "street": "Keizersgracht 1",
      "postal_code": "1015 CC",
      "city": "Amsterdam",
      "country": "NL"
    },
    "shipping_address": null,
    "currency": "EUR",
    "lines": [
      {
        "id": "8a9b0c1d-2e3f-4a4b-c5d6-e7f8a9b0c1d2",
        "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "variant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "variant_label": "Green / M",
        "name": "Garden Chair",
        "sku": "CHAIR-GRN-M",
        "quantity": 2,
        "unit": "piece",
        "unit_price": { "amount": 2250, "currency": "EUR" },
        "line_subtotal": { "amount": 3347, "currency": "EUR" },
        "tax_rate": 21,
        "tax": { "amount": 703, "currency": "EUR" },
        "line_total": { "amount": 4050, "currency": "EUR" },
        "attributes": { "returnable": true, "lead_time_days": null }
      }
    ],
    "subtotal": { "amount": 3347, "currency": "EUR" },
    "tax_total": { "amount": 789, "currency": "EUR" },
    "total": { "amount": 4545, "currency": "EUR" },
    "tax_breakdown": [{ "rate": 21, "base": 3756, "tax": 789 }],
    "discount_total": { "amount": 0, "currency": "EUR" },
    "discount_breakdown": null,
    "shipping_method_name": "Standard",
    "shipping": { "amount": 409, "currency": "EUR" },
    "shipping_tax": { "amount": 86, "currency": "EUR" },
    "tracking_carrier": "PostNL",
    "tracking_number": "3STEST123456",
    "invoice_number": null,
    "invoiced_at": null,
    "customer_id": null,
    "contact_id": null,
    "placed_at": "2026-08-14T10:15:30+00:00",
    "created_at": "2026-08-14T10:15:30+00:00",
    "invoice_id": null
  }
}

Fouten

StatusBodyWanneer
404{"message": "..."}Onbekend of soft-deleted bestelling-id, of een bestelling van een andere winkel.
403scope-, module- of suspensie-bodyKey mist commerce:read, module uitgeschakeld, of winkel geschorst.
429{"message": "Too Many Attempts."}Rate limit overschreden.

GET /v1/api/commerce/my/orders

Gepagineerde bestelgeschiedenis voor de klant geïdentificeerd door X-Customer-Token, gesorteerd op placed_at aflopend (nieuwste eerst). Het token is verplicht: dit is het endpoint achter de "mijn bestellingen"-pagina van een storefront. Gebruikt de standaard Laravel-paginatie-envelope.

Parameters

Query

NaamTypeVerplichtBeschrijving
per_pageintegerneePaginagrootte, standaard 25, begrensd tot 1..100.
pageintegerneePaginanummer, standaard 1.

Headers

NaamTypeVerplichtBeschrijving
X-Customer-TokenstringjaKlantsessietoken. Ontbrekend of niet herleidbaar: 401.
Request
curl "https://api.borkol.com/v1/api/commerce/my/orders?per_page=25&page=1" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: {customer_token}"
Request (JS)
const res = await fetch(
  "https://api.borkol.com/v1/api/commerce/my/orders?per_page=25",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "X-Customer-Token": customerToken,
    },
  }
);
const { data: orders, meta } = await res.json();
Response
{
  "data": [
    {
      "id": "7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1",
      "number": 1042,
      "status": "shipped",
      "email": "jane@example.com",
      "billing_address": {
        "name": "Jane Doe",
        "street": "Keizersgracht 1",
        "postal_code": "1015 CC",
        "city": "Amsterdam",
        "country": "NL"
      },
      "shipping_address": null,
      "currency": "EUR",
      "lines": [
        {
          "id": "8a9b0c1d-2e3f-4a4b-c5d6-e7f8a9b0c1d2",
          "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "variant_id": null,
          "variant_label": null,
          "name": "Garden Chair",
          "sku": "CHAIR-GRN",
          "quantity": 2,
          "unit": "piece",
          "unit_price": { "amount": 2250, "currency": "EUR" },
          "line_subtotal": { "amount": 3719, "currency": "EUR" },
          "tax_rate": 21,
          "tax": { "amount": 781, "currency": "EUR" },
          "line_total": { "amount": 4500, "currency": "EUR" },
          "attributes": { "returnable": true, "lead_time_days": 3 }
        }
      ],
      "subtotal": { "amount": 3719, "currency": "EUR" },
      "tax_total": { "amount": 867, "currency": "EUR" },
      "total": { "amount": 4995, "currency": "EUR" },
      "tax_breakdown": [{ "rate": 21, "base": 4128, "tax": 867 }],
      "discount_total": { "amount": 0, "currency": "EUR" },
      "discount_breakdown": null,
      "shipping_method_name": "Standard",
      "shipping": { "amount": 409, "currency": "EUR" },
      "shipping_tax": { "amount": 86, "currency": "EUR" },
      "tracking_carrier": "PostNL",
      "tracking_number": "3STEST123456",
      "invoice_number": null,
      "invoiced_at": null,
      "customer_id": "0a1b2c3d-4e5f-4a6b-7c8d-9e0f1a2b3c4d",
      "contact_id": "0a1b2c3d-4e5f-4a6b-7c8d-9e0f1a2b3c4d",
      "placed_at": "2026-08-10T14:02:11+00:00",
      "created_at": "2026-08-10T14:02:11+00:00",
      "invoice_id": null
    }
  ],
  "links": {
    "first": "https://api.borkol.com/v1/api/commerce/my/orders?page=1",
    "last": "https://api.borkol.com/v1/api/commerce/my/orders?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      { "url": null, "label": "« Previous", "active": false },
      { "url": "https://api.borkol.com/v1/api/commerce/my/orders?page=1", "label": "1", "active": true },
      { "url": null, "label": "Next »", "active": false }
    ],
    "path": "https://api.borkol.com/v1/api/commerce/my/orders",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Fouten

StatusBodyWanneer
401{"message": "Invalid customer token."}X-Customer-Token ontbreekt of is niet herleidbaar.
403scope-, module- of suspensie-bodyKey mist commerce:read, module uitgeschakeld, of winkel geschorst.
429{"message": "Too Many Attempts."}Rate limit overschreden.