borkoldocs

Orders & Quotes

Orders

Read a single order, list a customer's order history, and the order status machine.

View as Markdown

An order is created by checkout (or by accepting a quote) in status pending_payment. From the storefront API orders are read-only: all status changes (payment, shipment, refunds) happen merchant-side in the dashboard. Both endpoints require the commerce:read scope and the commerce module.

Order status

StatusMeaningCan transition to
pending_paymentCreated, awaiting payment.paid, cancelled
paidPayment received.shipped, cancelled, refunded
shippedHanded to the carrier; tracking fields may be set.completed, refunded
completedFulfilled.refunded
cancelledCancelled before fulfillment. Inventory is restocked.terminal
refundedRefunded. Inventory is restocked.terminal

Treat the enum as open: a client should render an unknown future status neutrally rather than fail.

The order response shape

Both endpoints serialize orders identically (single orders wrapped in {"data": {...}}, history entries as elements of a paginated data array). All money values are objects {"amount": int, "currency": "EUR"} with amount in minor units. Dates are ISO-8601 strings.

NameTypeRequiredDescription
idstring (UUID)alwaysOrder id.
numberintegeralwaysHuman-facing order number from a per-store counter. Plain integer, not a UUID.
statusstringalwaysSee the status table above.
emailstringalwaysThe email given at checkout.
billing_addressobjectalwaysThe billing address as submitted (name, street, postal_code, city, country).
shipping_addressobject or nullalwaysThe shipping address, or null when shipping to the billing address.
currencystringalwaysEUR.
linesarrayalwaysOrder lines, see below.
subtotalmoneyalwaysGoods total excluding tax.
tax_totalmoneyalwaysTotal tax including shipping tax.
totalmoneyalwaysGrand total including shipping.
tax_breakdownarrayalwaysPer-rate breakdown, each {"rate": float, "base": int, "tax": int}.
shipping_method_namestring or nullalwaysName snapshot of the chosen shipping method, null when no shipping applied.
shippingmoneyalwaysShipping cost excluding tax. amount is null when no shipping applied.
shipping_taxmoneyalwaysTax on shipping. amount is null when no shipping applied.
tracking_carrierstring or nullalwaysSet by the merchant when shipping.
tracking_numberstring or nullalwaysSet by the merchant when shipping.
invoice_numberinteger or nullalwaysPer-store invoice counter, set when the merchant invoices the order.
invoiced_atstring (ISO-8601) or nullalwaysWhen the order was invoiced.
customer_idstring (UUID) or nullalwaysThe customer the order is bound to, null for guest orders.
placed_atstring (ISO-8601) or nullalwaysWhen the order was placed.
created_atstring (ISO-8601) or nullalwaysRow creation time.

lines[]

NameTypeRequiredDescription
idstring (UUID)alwaysOrder line id.
product_idstring (UUID)alwaysThe product.
variant_idstring (UUID) or nullalwaysThe variant, when applicable.
variant_labelstring or nullalwaysHuman-readable variant label snapshot, for example "Green / M".
namestringalwaysProduct name snapshot.
skustring or nullalwaysSKU snapshot.
quantityintegeralwaysQuantity ordered.
unit_pricemoneyalwaysUnit price.
line_subtotalmoneyalwaysLine total excluding tax.
tax_ratenumberalwaysTax rate percentage applied to the line.
taxmoneyalwaysTax on the line.
line_totalmoneyalwaysLine total including tax.
attributesobject or nullalwaysNull for plain lines; the configuration snapshot for configurable products.

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

Fetches a single order with lines by id. There is no customer-ownership check on this endpoint: it is authorized purely by the tenant API key, which is a server-side secret. It exists for the storefront server, for example rendering the order-confirmation page right after checkout. Never proxy it to browsers with a client-supplied order id unless your server performs its own ownership check first.

Parameters

Path

NameTypeRequiredDescription
idstring (UUID)yesOrder 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_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": 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 }],
    "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,
    "placed_at": "2026-08-14T10:15:30+00:00",
    "created_at": "2026-08-14T10:15:30+00:00"
  }
}

Errors

StatusBodyWhen
404{"message": "..."}Unknown or soft-deleted order id, or an order of another store.
403scope, module, or suspension bodyKey lacks commerce:read, module disabled, or store suspended.
429{"message": "Too Many Attempts."}Rate limit exceeded.

GET /v1/api/commerce/my/orders

Paginated order history for the customer identified by X-Customer-Token, sorted by placed_at descending (newest first). The token is mandatory: this is the endpoint behind a storefront's "my orders" page. Uses the standard Laravel pagination envelope.

Parameters

Query

NameTypeRequiredDescription
per_pageintegernoPage size, default 25, clamped to 1..100.
pageintegernoPage number, default 1.

Headers

NameTypeRequiredDescription
X-Customer-TokenstringyesCustomer session token. Missing or unresolvable: 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_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": null
        }
      ],
      "subtotal": { "amount": 3719, "currency": "EUR" },
      "tax_total": { "amount": 867, "currency": "EUR" },
      "total": { "amount": 4995, "currency": "EUR" },
      "tax_breakdown": [{ "rate": 21, "base": 4128, "tax": 867 }],
      "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",
      "placed_at": "2026-08-10T14:02:11+00:00",
      "created_at": "2026-08-10T14:02:11+00:00"
    }
  ],
  "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
  }
}

Errors

StatusBodyWhen
401{"message": "Invalid customer token."}X-Customer-Token missing or unresolvable.
403scope, module, or suspension bodyKey lacks commerce:read, module disabled, or store suspended.
429{"message": "Too Many Attempts."}Rate limit exceeded.