Import History
POST/api/ledger/history/imports
Import counts or purchases from a CSV or XLSX file (up to 20 MB). The import runs in the background; the response gives the job id to follow. Rows upsert on their natural key (counts: date, warehouse and SKU; purchases: date, document, SKU and warehouse), so importing the same file again updates rows instead of duplicating them. Each row is validated first; a bad row is rejected with its reason and the rest import. The finished job's results list created, updated and each rejected row (row, date, warehouse, sku, problem).
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Count columns: date, warehouse, sku, quantity, unit_cost, basis, cost_basis, reference, note. Purchase columns: date, supplier, document, sku, warehouse, quantity, unit_cost, landed_cost, cost_basis, note, source_document.
Headers match case-insensitively. Dates are YYYY-MM-DD or MM/DD/YYYY. sku matches a product's SKU, then a supplier SKU, then a barcode. warehouse is a name or id; when blank, the account's only warehouse is used. landed_cost is for the whole line. source_document is stored on the row's note.
Authentication: Requires Bearer token + accounting.manage_settings permission.
Optional: default_warehouse_id: the warehouse for purchase lines whose file has none. The purchases file also accepts a received_on column.
Request
Responses
- 202
- 401
- 403
- 422
- 429
Accepted
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.