BoxLatviaDevelopers
Get access
API reference

Orders

The paid orders of your boxes, read only. Use them to see who rented what and when, and to catch up after an interruption.

Note
An order shows up here when the renter has paid; an order that was never paid is not shown. The API only reads: orders are confirmed in the partner portal. The renter's contact details are personal data: reading orders needs the scope orders:read, which BoxLatvia grants on purpose. To learn the moment an order is placed, use Webhooks.

#The Order object

NameTypeDescription
iduuidBoxLatvia's identifier.
referencestringThe order number the renter and BoxLatvia quote.
statusstringPAID, REFUNDED or CANCELLED. An order that was never paid is not shown.
deal_statusstring | nullAWAITING: the box owner has until confirm_deadline to confirm the rental. CONFIRMED, or FAILED (not confirmed in time, or the rental will not happen).
confirm_deadline confirmed_at failed_atdatetime | nullWhen the rental must be confirmed by, when it was confirmed, when it failed. ISO 8601, UTC.
box_iduuid | nullThe box that was rented.
box_external_idstring | nullYour own identifier of the box, if you set one.
location_iduuid | nullThe box's location.
location_external_idstring | nullYour own identifier of the location.
rent_from rent_todate | nullThe rental period, YYYY-MM-DD.
rental_unitsinteger | nullNumber of rental periods (for example months).
unit_pricenumber | nullPrice of one period.
amount currencynumber, stringWhat the renter paid, and the currency (EUR).
extra_servicesstring[]Extra services the renter chose, if any.
customerobject{ name, email, phone } of the renter. Contains the renter's name, e-mail and phone: personal data. Use it only to hand over the box and to serve the rental.
paid_at refunded_atdatetime | nullWhen the order was paid, and when it was refunded. ISO 8601, UTC.
created_atdatetimeISO 8601, UTC.
updated_atdatetimeChanges whenever the order changes. Use it with updated_since to ask what changed. ISO 8601, UTC.
Example
{
  "id": "614211b3-38be-4ba5-94e2-6f177542a174",
  "reference": "ORD-MI3K7ZQ0-4F2A",
  "status": "PAID",
  "deal_status": "AWAITING",
  "confirm_deadline": "2026-11-15T09:12:30.000Z",
  "confirmed_at": null,
  "failed_at": null,
  "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
  "box_external_id": "SKU-3M",
  "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
  "location_external_id": "WH-IMANTA",
  "rent_from": "2026-12-01",
  "rent_to": "2027-02-28",
  "rental_units": 3,
  "unit_price": 31.5,
  "amount": 94.5,
  "currency": "EUR",
  "extra_services": [],
  "customer": {
    "name": "Jānis Ozols",
    "email": "janis.ozols@example.com",
    "phone": "+371 20000001"
  },
  "paid_at": "2026-11-14T09:12:30.000Z",
  "refunded_at": null,
  "created_at": "2026-11-14T09:10:02.000Z",
  "updated_at": "2026-11-14T09:12:30.000Z"
}

#Endpoints

#List orders

GET/v1/ordersorders:read

The paid orders of your boxes, oldest change first, one page at a time. Read only.

Use this to start from a full picture and to catch up after an outage: remember the updated_at of the last order you processed and next time ask for updated_since that value. An order with exactly that time comes again, so ignore orders you already have. See also Webhooks, which tell you the moment something happens.

Contains the renter's name, e-mail and phone: personal data. Use it only to hand over the box and to serve the rental.

Query parameters

NameTypeDescription
limitintegerPage size, 1 to 200. Default 50.
cursorstringThe next_cursor of the previous page. Do not build cursors yourself.
statusstringPAID, REFUNDED or CANCELLED.
deal_statusstringAWAITING, CONFIRMED or FAILED.
box_iduuidOnly orders of this box.
box_external_idstringOnly orders of the box with this identifier of yours.
referencestringOnly the order with this order number.
updated_sincedatetimeOnly orders changed at or after this time, for example 2026-11-14T09:00:00Z.

Examples

The first page of orders
curl "$API/v1/orders?limit=2" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "data": [
    {
      "id": "614211b3-38be-4ba5-94e2-6f177542a174",
      "reference": "ORD-MI3K7ZQ0-4F2A",
      "status": "PAID",
      "deal_status": "AWAITING",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": null,
      "failed_at": null,
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-12-01",
      "rent_to": "2027-02-28",
      "rental_units": 3,
      "unit_price": 31.5,
      "amount": 94.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Jānis Ozols",
        "email": "janis.ozols@example.com",
        "phone": "+371 20000001"
      },
      "paid_at": "2026-11-14T09:12:30.000Z",
      "refunded_at": null,
      "created_at": "2026-11-14T09:10:02.000Z",
      "updated_at": "2026-11-14T09:12:30.000Z"
    },
    {
      "id": "7975c57c-2ef3-40dc-a2d5-0c0c2533b541",
      "reference": "ORD-MI3L1B90-9C1D",
      "status": "PAID",
      "deal_status": "CONFIRMED",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": "2026-11-14T10:05:11.000Z",
      "failed_at": null,
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-11-20",
      "rent_to": "2026-12-19",
      "rental_units": 1,
      "unit_price": 31.5,
      "amount": 31.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Marta Liepiņa",
        "email": "marta.liepina@example.com",
        "phone": "+371 20000002"
      },
      "paid_at": "2026-11-14T09:40:00.000Z",
      "refunded_at": null,
      "created_at": "2026-11-14T09:38:41.000Z",
      "updated_at": "2026-11-14T10:05:11.000Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTExLTE0IDEwOjA1OjExLjAwMCswMCIsIjk2MzViNDE5LThlNzQtNGQ5YS1iOTRjLTRmMzQxMmQ2MzEyZCJd"
}
What changed since a time

Orders are ordered by change time, so you can keep a bookmark.

curl "$API/v1/orders?updated_since=2026-11-14T10:00:00Z&box_external_id=SKU-3M" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "data": [
    {
      "id": "7975c57c-2ef3-40dc-a2d5-0c0c2533b541",
      "reference": "ORD-MI3L1B90-9C1D",
      "status": "PAID",
      "deal_status": "CONFIRMED",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": "2026-11-14T10:05:11.000Z",
      "failed_at": null,
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-11-20",
      "rent_to": "2026-12-19",
      "rental_units": 1,
      "unit_price": 31.5,
      "amount": 31.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Marta Liepiņa",
        "email": "marta.liepina@example.com",
        "phone": "+371 20000002"
      },
      "paid_at": "2026-11-14T09:40:00.000Z",
      "refunded_at": null,
      "created_at": "2026-11-14T09:38:41.000Z",
      "updated_at": "2026-11-14T10:05:11.000Z"
    },
    {
      "id": "5aad7dee-7f4b-4ca3-a908-b0a87b8792b6",
      "reference": "ORD-MI3M5X44-27E8",
      "status": "REFUNDED",
      "deal_status": "FAILED",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": null,
      "failed_at": "2026-11-14T11:20:00.000Z",
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-12-01",
      "rent_to": "2027-02-28",
      "rental_units": 3,
      "unit_price": 31.5,
      "amount": 94.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Pēteris Kalniņš",
        "email": "peteris.kalnins@example.com",
        "phone": null
      },
      "paid_at": "2026-11-14T09:50:00.000Z",
      "refunded_at": "2026-11-14T11:20:00.000Z",
      "created_at": "2026-11-14T09:48:10.000Z",
      "updated_at": "2026-11-14T11:20:00.000Z"
    }
  ],
  "next_cursor": null
}
Invalid filters
curl "$API/v1/orders?status=maybe&updated_since=yesterday" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
422 Unprocessable Content
{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "22879f48-8c91-4c54-aab3-ef1cb47b2dec",
  "errors": [
    {
      "field": "status",
      "message": "must be one of PAID, REFUNDED, CANCELLED"
    },
    {
      "field": "updated_since",
      "message": "must be an ISO 8601 date or date and time, for example 2026-11-13T09:00:00Z"
    }
  ]
}

Errors

StatusWhen
403The credentials lack orders:read.
422A filter is not valid; every problem is listed.

#Read an order

GET/v1/orders/{id}orders:read

One order.

Path parameters

NameTypeDescription
iduuidThe order's id.

Examples

An order
curl "$API/v1/orders/614211b3-38be-4ba5-94e2-6f177542a174" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "id": "614211b3-38be-4ba5-94e2-6f177542a174",
  "reference": "ORD-MI3K7ZQ0-4F2A",
  "status": "PAID",
  "deal_status": "AWAITING",
  "confirm_deadline": "2026-11-15T09:12:30.000Z",
  "confirmed_at": null,
  "failed_at": null,
  "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
  "box_external_id": "SKU-3M",
  "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
  "location_external_id": "WH-IMANTA",
  "rent_from": "2026-12-01",
  "rent_to": "2027-02-28",
  "rental_units": 3,
  "unit_price": 31.5,
  "amount": 94.5,
  "currency": "EUR",
  "extra_services": [],
  "customer": {
    "name": "Jānis Ozols",
    "email": "janis.ozols@example.com",
    "phone": "+371 20000001"
  },
  "paid_at": "2026-11-14T09:12:30.000Z",
  "refunded_at": null,
  "created_at": "2026-11-14T09:10:02.000Z",
  "updated_at": "2026-11-14T09:12:30.000Z"
}
An order that is not yours
curl "$API/v1/orders/74c1f875-f6e8-4d9c-bcd3-52032635d35a" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
404 Not Found
{
  "type": "https://api.boxlatvia.lv/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such order.",
  "request_id": "4c9a8e0d-9587-4f2f-8780-48a10da5842b"
}

Errors

StatusWhen
404No such order of yours, or it was never paid.