Skip to main content

​
Items

The Items API provides CRUD access to the product/service catalog. Catalog items populate invoice and estimate line items.
New to the API? Start with Getting started (base URL, response envelope, errors, pagination) and Authentication (API keys).
Identifier note: items are addressed by their numeric item_id.
An item sits under an item category (a category of type item) and carries a unit, a rate and a default tax rate.
Scope: production tasks, bulk change-category, pinning, import and the purchasing/stock module are out of API scope. Items have no tags.

​
The item object

{
  "id": 28,
  "type": "standard",
  "description": "Logo Design",
  "notes": null,
  "rate": "200.00",
  "tax_status": "taxable",
  "default_tax": { "id": 1, "name": "VAT" },
  "unit": { "id": 4, "name": "Pcs" },
  "category": { "id": 8, "name": "Default" },
  "creator_id": 1,
  "estimation_notes": null,
  "custom_fields": [ { "id": 1, "name": "ISBN", "value": "ISBN-978-3-16-148410-0" } ],
  "dates": { "created": "...", "updated": "..." }
}
FieldTypeNotes
idintegerItem id.
description / notesstring
ratenumericUnit rate.
default_taxobjectThe default tax rate (id, name).
unitobjectThe unit of measure (id, name).
categoryobjectThe item category.
estimation_notesstringOptional estimation note.
custom_fieldsarrayEnabled item custom fields with their values (id, name, value).

​
List / search items

GET /api/items
Query params: category_id, unit_id, tax_rate_id, rate_min, rate_max, search, sort (item_description,item_rate,item_created), order, limit, page. 
curl -G https://your-domain/api/items -H "Authorization: Bearer YOUR_API_KEY" -d category_id=8

​
Get an item

GET /api/items/{id}

​
Create an item

POST /api/items
ParameterTypeRequiredNotes
item_descriptionstringyes
item_ratenumericyes
item_categoryidintegeryesA category of type item.
item_default_taxintegeryesA taxrate_id (use the “No Tax” rate for tax-free items).
item_unitmixedyesAn existing unit_id, or a new unit name (auto-created).
item_notesstringno
item_notes_estimatationstringno
item_custom_field_1..10mixednoValues for enabled item custom fields.
curl -X POST https://your-domain/api/items -H "Authorization: Bearer YOUR_API_KEY" \
  -d item_description="Logo Design" -d item_rate=200 -d item_categoryid=8 \
  -d item_default_tax=1 -d item_unit=Hours -d item_custom_field_1="ISBN-001"
Returns the new item (201).

​
Update an item

PATCH /api/items/{id}
Same fields as create. 
curl -X PATCH https://your-domain/api/items/28 -H "Authorization: Bearer YOUR_API_KEY" \
  -d item_description="Logo Design" -d item_rate=250 -d item_categoryid=8 \
  -d item_default_tax=1 -d item_unit=4

​
Delete an item

DELETE /api/items/{id}

​
Errors

See Getting started. Item-specific:
StatusMeaning
404 Not FoundThe item id does not exist.
422 Unprocessable EntityValidation failed (missing fields, non-item category, invalid tax rate, or an invalid unit name).