Import items from CSV

POST/v1/items/import

Creates or updates many items at once from a CSV file.

Send the file as multipart/form-data in the field file. The first row must be a header with any of: name, description, sku, unit, unit_price, currency, tax_rate. unit_price is a decimal in the file (e.g. 450.00) and is converted to minor units with the currency's decimals.

Rows whose sku matches an existing item update that item; other rows create new items. The response reports every row that failed and why, and nothing from a failed row is saved.

Permission: items.manage
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: import_items
CLI: freeinvoiceautomation item import
Available: At launch, 1 January 2027

import_items

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/items/import \
  --header 'Authorization: Bearer <api-key>' \
  --form file=@./file.csv

{
  "data": {
    "created": 42,
    "updated": 3,
    "failed": [
      {
        "row": 17,
        "message": "unit_price is not a number"
      }
    ]
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Body

multipart/form-data

filefilerequired

CSV file, UTF-8, up to 5 MB.

business_idstring<uuid>

Business to import into.

Response

200 - application/json

createdinteger

Number of new items.

updatedinteger

Number of items updated by SKU.

failedobject[]

Rows that were not imported.

Errors

validation_failed

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

Archive an itemPrevious Export items to CSVNext

import_items

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/items/import \
  --header 'Authorization: Bearer <api-key>' \
  --form file=@./file.csv

{
  "data": {
    "created": 42,
    "updated": 3,
    "failed": [
      {
        "row": 17,
        "message": "unit_price is not a number"
      }
    ]
  }
}