Import from Excel
Prefer a spreadsheet to calls? Fill in an Excel file, send it to the API, and your locations, boxes and pictures are created or updated in one go. The same file can be sent again whenever something changes.
#How it works
-
#Download the templates
One file for each kind. Each has the column names, dropdowns, instructions, an example sheet and the lists of codes.
For Template Rows per file Locations Download (.xlsx, English) latviski 500 Boxes Download (.xlsx, English) latviski 500 Pictures Download (.xlsx, English) latviski 50 -
#Fill in the Data sheet
One row per location, box or picture. Keep the column names in the first row. Leave a cell empty to leave that value as it is. Import in this order: locations, then boxes, then pictures, because a box needs its location and a picture needs its box.
-
#Check it first
Send the file with
?validate_only=true. Every check runs, nothing is saved, and the answer lists what would happen to every row and every problem in it.Check a filecurl -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)" } ] } ] } -
#Send it
The same request without
?validate_only=true. Fix the rows that failed, and send the file again: rows that are already right are simply found unchanged.Importcurl -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" } ] } ] }
#The columns
The column names are the API's own field names, so a column means the same here as in the boxes, locations and pictures reference. Codes come from the reference data and are listed on the template's Codes sheet.
#Locations
| Column | Type | Description |
|---|---|---|
external_id | text | always. Your own identifier of the location (up to 100 characters). It decides whether a row creates a new location or updates an existing one. |
name | text | for a new record. Name of the location, up to 100 characters. Required for a new location. |
description | text | Description, up to 250 characters. |
address | text | Address, up to 250 characters. |
district | text | District code, from the Codes sheet. |
latitude | number | Latitude, a number from -90 to 90. Give together with longitude. |
longitude | number | Longitude, a number from -180 to 180. Give together with latitude. |
features | codes, separated by commas | Amenity codes from the Codes sheet, separated by commas. Replaces the whole set. At least 5 are needed for customers to find the location. |
#Boxes
| Column | Type | Description |
|---|---|---|
external_id | text | always. Your own identifier of the box (up to 100 characters). It decides whether a row creates a new box or updates an existing one. |
name | text | for a new record. Name of the box, up to 255 characters. Required for a new box. |
location_external_id | text | for a new record. The external_id of the location the box is in. Required for a new box. The location must exist already (import locations first). |
description | text | Description, up to 255 characters. |
price | number | Price per period, more than 0, at most 2 decimals. |
promotional_price | number | Discounted price. Must be lower than price. |
price_period_1 | number | Optional fixed total for renting 1 period. |
price_period_3 | number | Optional fixed total for renting 3 periods. |
price_period_6 | number | Optional fixed total for renting 6 periods. |
price_period_12 | number | Optional fixed total for renting 12 periods. |
price_unit | text | Price unit code from the Codes sheet (per month, per week). |
size | number | Floor area in m², more than 0. |
size_length | number | Inner length in metres. |
size_width | number | Inner width in metres. |
size_height | number | Inner height in metres. |
door_width | number | Door width in metres. |
door_height | number | Door height in metres. |
total_units | whole number | How many identical boxes you have, a whole number, 0 or more. |
available_units | whole number | How many are free to rent right now. Cannot exceed total_units. |
max_advance_days | whole number | How many days ahead a customer may book, 1 to 730. |
features | codes, separated by commas | Amenity codes from the Codes sheet, separated by commas. Replaces the whole set. |
#Pictures
| Column | Type | Description |
|---|---|---|
owner | text | always. What the picture belongs to: box or location. |
external_id | text | always. The external_id of that box or location. It must exist already. |
picture_url | text | always. Public address (https) of the picture file: JPEG, PNG, WebP or GIF, up to 5 MB. BoxLatvia fetches it and stores its own copy. |
#Rules to know
- The identifier decides. A row with an
external_idyou used before updates that record; a new one creates a record. Each identifier can appear once per file. - An empty cell means "leave it". That makes a stock feed easy: a file with only
external_idandavailable_unitschanges nothing but the stock. A value that is saved cannot be cleared with a file; do that with the API. featuresreplaces the whole set when the cell is filled in: write all the codes you want, separated by commas.- Numbers can be written with a dot or a comma (
29.90or29,90). The same checks as in the API apply: prices have at most 2 decimals, the promotional price is lower than the price, available units do not exceed total units. - Boxes start as drafts. An import never publishes: submit boxes for review through the API or the partner portal.
- CSV works too. Save as CSV UTF-8; commas, semicolons (Excel in Latvian) and tabs are recognised. An old
.xlsfile must be saved as.xlsxfirst.
#Pictures
A picture row names the owner (box or location), its external_id and the address (https) of the picture. BoxLatvia fetches the picture and keeps its own copy, so your own file does not need to stay online.
- JPEG, PNG, WebP or GIF, up to 5 MB each; the content is checked, not the file name. At most 20 pictures per box or location.
- The address must be public:
httpsand a host name (not an IP address, not a private network). Redirects are followed a few times, with the same checks. - Sending the same picture again does nothing: it is recognised and counted as unchanged. Pictures are only added; to remove one, use the API.
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()){
"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"
}
]
}
]
}#Reading the answer
The answer is 200 whenever the file could be read, even if some rows failed. Look at summary for the totals and at each entry of rows:
| Status | Meaning |
|---|---|
created | A new record was created (for pictures: the picture was added). |
updated | An existing record was changed. |
unchanged | Nothing to change: the row had no values, or the picture was already there. |
failed | The row was not saved; errors lists every problem as { field, message }. |
would_create / would_update | Only with validate_only: what would happen. |
row is the row number as Excel shows it (the header is row 1), so you can go straight to the cell. A problem with the whole file is a 422 instead:
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()){
"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"
}
]
}Idempotency-Key if a request might have timed out.#Limits
| Limit | Value |
|---|---|
| Rows per file | 500 for locations and boxes, 50 for pictures |
| File size | 10 MB |
| Columns | 60 |
| Text in a cell | 5000 characters (the field limits are lower) |
You need the scope imports:write, which lets the credentials create and change locations, boxes and pictures through files. BoxLatvia grants it on request: request access.