API reference
Import
Send an Excel or CSV file; every row creates or updates a location, a box or a picture. Everything about filling in the files is in the import guide.
#The import report
| Name | Type | Description |
|---|---|---|
kind | string | locations, boxes or pictures. |
validate_only | boolean | true when the file was only checked. |
summary | object | { total, created, updated, unchanged, failed }. For pictures, created counts the pictures added. |
rows | object[] | One entry per data row: row (as Excel shows it), external_id, status, id of the record, and errors for a failed row. |
#Endpoint
#Import a file
POST
/v1/imports/{kind}imports:writeCreates or updates locations, boxes or pictures from an Excel (.xlsx) or CSV file, one row each. The answer says what happened to every row.
- Start from the template for the kind: its columns are the ones the importer reads.
- A row's
external_id(your own identifier) decides: it exists → the row updates it, an empty cell leaves the value as it is; it does not exist → the row creates it. - Rows are independent. A row that fails does not stop the others, and the answer lists all its problems at once.
?validate_only=trueruns every check, fetches the pictures, and saves nothing: use it before the real import.- Up to 500 rows per file for locations and boxes, 50 for pictures. Larger files: split them.
Path parameters
| Name | Type | Description |
|---|---|---|
kind | string | locations, boxes or pictures. |
Query parameters
| Name | Type | Description |
|---|---|---|
validate_only | boolean | true: check everything and save nothing. Statuses are then would_create / would_update. |
Headers
| Name | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional. A retry with the same key returns the first answer instead of importing again. |
Request body (multipart/form-data)
| Name | Type | Description |
|---|---|---|
file required | file | One .xlsx or .csv file. The sheet called Data (or Dati) is read, or the first sheet. |
Examples
Check a locations file first
Nothing is saved: the statuses say what would happen, and every problem of every row is listed.
curl -X POST "$API/v1/imports/locations?validate_only=true" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-locations.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_locationsFile); // a File or Blob
const res = await fetch(`${API}/v1/imports/locations?validate_only=true`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/locations?validate_only=true",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-locations.xlsx", "rb"))],
)
print(r.status_code, r.json())200 OKX-Validate-Only: true
{
"kind": "locations",
"validate_only": true,
"summary": {
"total": 3,
"created": 1,
"updated": 1,
"unchanged": 0,
"failed": 1
},
"rows": [
{
"row": 2,
"external_id": "WH-IMANTA",
"status": "would_update",
"id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
},
{
"row": 3,
"external_id": "WH-KENGARAGS",
"status": "would_create"
},
{
"row": 4,
"external_id": "WH-NOWHERE",
"status": "failed",
"errors": [
{
"field": "district",
"message": "\"atlantis\" is not a known district code (see the Codes sheet)"
}
]
}
]
}Import the locations
curl -X POST "$API/v1/imports/locations" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-locations.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_locationsFile); // a File or Blob
const res = await fetch(`${API}/v1/imports/locations`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/locations",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-locations.xlsx", "rb"))],
)
print(r.status_code, r.json())200 OK
{
"kind": "locations",
"validate_only": false,
"summary": {
"total": 2,
"created": 1,
"updated": 1,
"unchanged": 0,
"failed": 0
},
"rows": [
{
"row": 2,
"external_id": "WH-IMANTA",
"status": "updated",
"id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
},
{
"row": 3,
"external_id": "WH-KENGARAGS",
"status": "created",
"id": "3f502d49-40f5-43e8-8004-dc4bb2f28a99"
}
]
}Boxes: one updated, one created, one with problems
The first row only sends available_units: a stock update. Everything else on that box stays.
curl -X POST "$API/v1/imports/boxes" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-boxes.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_boxesFile); // a File or Blob
const res = await fetch(`${API}/v1/imports/boxes`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/boxes",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-boxes.xlsx", "rb"))],
)
print(r.status_code, r.json())200 OK
{
"kind": "boxes",
"validate_only": false,
"summary": {
"total": 3,
"created": 1,
"updated": 1,
"unchanged": 0,
"failed": 1
},
"rows": [
{
"row": 2,
"external_id": "SKU-3M",
"status": "updated",
"id": "c4883b4a-4e38-47bf-8a69-ef025917e022"
},
{
"row": 3,
"external_id": "SKU-8M",
"status": "created",
"id": "e8e189c3-3ac4-47d0-8ff1-584221c4e1ae"
},
{
"row": 4,
"external_id": "SKU-9M",
"status": "failed",
"errors": [
{
"field": "price_unit",
"message": "\"gadsimts\" is not a known price unit code (see the Codes sheet)"
},
{
"field": "price",
"message": "must have at most 2 decimals"
}
]
}
]
}Pictures by address
curl -X POST "$API/v1/imports/pictures" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-pictures.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_picturesFile); // a File or Blob
const res = await fetch(`${API}/v1/imports/pictures`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/pictures",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-pictures.xlsx", "rb"))],
)
print(r.status_code, r.json())200 OK
{
"kind": "pictures",
"validate_only": false,
"summary": {
"total": 3,
"created": 2,
"updated": 0,
"unchanged": 0,
"failed": 1
},
"rows": [
{
"row": 2,
"external_id": "WH-IMANTA",
"status": "created",
"id": "734e0d86-9a60-4107-9997-c9f0bcf77610"
},
{
"row": 3,
"external_id": "SKU-3M",
"status": "created",
"id": "d504c7e6-8458-456a-884d-0b4ba02be2d3"
},
{
"row": 4,
"external_id": "SKU-3M",
"status": "failed",
"errors": [
{
"field": "picture_url",
"message": "the address answered HTTP 404"
}
]
}
]
}A file that cannot be used
curl -X POST "$API/v1/imports/boxes" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-boxes.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_boxesFile); // a File or Blob
const res = await fetch(`${API}/v1/imports/boxes`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/boxes",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-boxes.xlsx", "rb"))],
)
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": "88b1f62d-3509-4d1f-b542-ff67a35787ae",
"errors": [
{
"field": "columns",
"message": "unknown column(s): nane, colour. The columns of this file are: external_id, name, location_external_id, description, price, promotional_price, price_period_1, price_period_3, price_period_6, price_period_12, price_unit, size, size_length, size_width, size_height, door_width, door_height, total_units, available_units, max_advance_days, features"
}
]
}Errors
| Status | When |
|---|---|
| 403 | The credentials lack imports:write. |
| 404 | kind is not locations, boxes or pictures. |
| 415 | Not multipart/form-data, or an old .xls file: save it as .xlsx or .csv. |
| 422 | The file as a whole cannot be used: unknown or missing columns, no data rows, too many rows, unreadable. Problems with single rows are in the answer (status 200), not here. |