BoxLatviaDevelopers
Get access
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

NameTypeDescription
kindstringlocations, boxes or pictures.
validate_onlybooleantrue when the file was only checked.
summaryobject{ total, created, updated, unchanged, failed }. For pictures, created counts the pictures added.
rowsobject[]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:write

Creates 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=true runs 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

NameTypeDescription
kindstringlocations, boxes or pictures.

Query parameters

NameTypeDescription
validate_onlybooleantrue: check everything and save nothing. Statuses are then would_create / would_update.

Headers

NameTypeDescription
Idempotency-KeystringOptional. A retry with the same key returns the first answer instead of importing again.

Request body (multipart/form-data)

NameTypeDescription
file requiredfileOne .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"
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"
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"
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"
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"
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

StatusWhen
403The credentials lack imports:write.
404kind is not locations, boxes or pictures.
415Not multipart/form-data, or an old .xls file: save it as .xlsx or .csv.
422The 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.