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
| Name | Type | Description |
|---|---|---|
id | uuid | BoxLatvia's identifier. |
reference | string | The order number the renter and BoxLatvia quote. |
status | string | PAID, REFUNDED or CANCELLED. An order that was never paid is not shown. |
deal_status | string | null | AWAITING: 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_at | datetime | null | When the rental must be confirmed by, when it was confirmed, when it failed. ISO 8601, UTC. |
box_id | uuid | null | The box that was rented. |
box_external_id | string | null | Your own identifier of the box, if you set one. |
location_id | uuid | null | The box's location. |
location_external_id | string | null | Your own identifier of the location. |
rent_from rent_to | date | null | The rental period, YYYY-MM-DD. |
rental_units | integer | null | Number of rental periods (for example months). |
unit_price | number | null | Price of one period. |
amount currency | number, string | What the renter paid, and the currency (EUR). |
extra_services | string[] | Extra services the renter chose, if any. |
customer | object | { 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_at | datetime | null | When the order was paid, and when it was refunded. ISO 8601, UTC. |
created_at | datetime | ISO 8601, UTC. |
updated_at | datetime | Changes 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:readThe 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
| Name | Type | Description |
|---|---|---|
limit | integer | Page size, 1 to 200. Default 50. |
cursor | string | The next_cursor of the previous page. Do not build cursors yourself. |
status | string | PAID, REFUNDED or CANCELLED. |
deal_status | string | AWAITING, CONFIRMED or FAILED. |
box_id | uuid | Only orders of this box. |
box_external_id | string | Only orders of the box with this identifier of yours. |
reference | string | Only the order with this order number. |
updated_since | datetime | Only 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"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const res = await fetch(`${API}/v1/orders?limit=2`, {
headers: { Authorization: auth },
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.get(
f"{API}/v1/orders?limit=2",
auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())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"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const res = await fetch(`${API}/v1/orders?updated_since=2026-11-14T10:00:00Z&box_external_id=SKU-3M`, {
headers: { Authorization: auth },
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.get(
f"{API}/v1/orders?updated_since=2026-11-14T10:00:00Z&box_external_id=SKU-3M",
auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())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"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const res = await fetch(`${API}/v1/orders?status=maybe&updated_since=yesterday`, {
headers: { Authorization: auth },
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.get(
f"{API}/v1/orders?status=maybe&updated_since=yesterday",
auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())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
| Status | When |
|---|---|
| 403 | The credentials lack orders:read. |
| 422 | A filter is not valid; every problem is listed. |
#Read an order
GET
/v1/orders/{id}orders:readOne order.
Path parameters
| Name | Type | Description |
|---|---|---|
id | uuid | The order's id. |
Examples
An order
curl "$API/v1/orders/614211b3-38be-4ba5-94e2-6f177542a174" \
-u "$CLIENT_ID:$CLIENT_SECRET"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const res = await fetch(`${API}/v1/orders/614211b3-38be-4ba5-94e2-6f177542a174`, {
headers: { Authorization: auth },
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.get(
f"{API}/v1/orders/614211b3-38be-4ba5-94e2-6f177542a174",
auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())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"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const res = await fetch(`${API}/v1/orders/74c1f875-f6e8-4d9c-bcd3-52032635d35a`, {
headers: { Authorization: auth },
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.get(
f"{API}/v1/orders/74c1f875-f6e8-4d9c-bcd3-52032635d35a",
auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())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
| Status | When |
|---|---|
| 404 | No such order of yours, or it was never paid. |