Items

Items represent products and services that can be used as line items in invoices and other commercial documents. The items API allows you to manage a catalog of reusable items, group them into collections (templates, carts, orders), and look up standard measurement units.

Item Endpoints

List Items

GET /api/v2/items

Retrieves a paginated list of items.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "client_account_id": 7,
      "item_no": "PROD-001",
      "name": "Web Development Service",
      "item_type": "SERVICE",
      "sales_unit_id": 5,
      "stock_unit_id": null,
      "tax_code_id": 3,
      "price": "1500.000000",
      "metadata": null,
      "is_active": true
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "records": 1
  }
}

Get Item

GET /api/v2/items/{id}

Retrieves a specific item by ID.

Query Parameters

Response

{
  "id": 1,
  "client_account_id": 7,
  "item_no": "PROD-001",
  "name": "Web Development Service",
  "item_type": "SERVICE",
  "sales_unit_id": 5,
  "stock_unit_id": null,
  "tax_code_id": 3,
  "price": "1500.000000",
  "metadata": null,
  "is_active": true
}

Create Item

POST /api/v2/items

Creates a new item.

Request Body

Example Request

{
  "client_account_id": 7,
  "item_no": "PROD-001",
  "name": "Web Development Service",
  "item_type": "SERVICE",
  "sales_unit_id": 5,
  "tax_code_id": 3,
  "price": "1500"
}

Response

Returns the created item with status 201 Created.

Update Item

PUT /api/v2/items/{id}

Updates an existing item. The client_account_id cannot be changed after creation.

Request Body

Same fields as Create Item, except client_account_id is immutable.

Response

Returns the updated item with status 200 OK.

Deactivate Item

DELETE /api/v2/items/{id}

Deactivates an item by setting its is_active status to false. The item record is preserved for historical purposes.

Response

Returns the deactivated item with is_active: false and status 200 OK.

Item Collection Endpoints

Item collections group items into reusable sets such as invoice templates, shopping carts, or orders.

List Item Collections

GET /api/v2/item-collections

Retrieves a paginated list of item collections.

Query Parameters

Response

{
  "data": [
    {
      "id": 10,
      "client_account_id": 7,
      "name": "Monthly Retainer",
      "collection_type": "TEMPLATE"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Get Item Collection

GET /api/v2/item-collections/{id}

Retrieves a specific item collection by ID. Entries are included by default.

Response

{
  "id": 10,
  "client_account_id": 7,
  "name": "Monthly Retainer",
  "collection_type": "TEMPLATE",
  "entries": [
    {
      "id": 100,
      "item_collection_id": 10,
      "item_id": 1,
      "description": "Web Development Service",
      "quantity": "10.000000",
      "price": "1500.000000",
      "currency_code": "NOK",
      "unit_id": 5,
      "tax_code_id": 3,
      "business_partner_id": null,
      "project_id": null,
      "recurring_start_date": null,
      "recurring_end_date": null,
      "recurring_terms": null,
      "recurring_interval": null,
      "refund_policy": null,
      "trial_end_date": null,
      "created_at": "2024-03-15T10:00:00Z",
      "created_by_id": 7,
      "updated_at": null,
      "updated_by_id": null
    }
  ]
}

Create Item Collection

POST /api/v2/item-collections

Creates a new item collection.

Request Body

Example Request

{
  "client_account_id": 7,
  "name": "Monthly Retainer",
  "collection_type": "TEMPLATE"
}

Response

Returns the created collection with status 201 Created.

List Collection Entries

GET /api/v2/item-collections/{id}/entries

Retrieves entries within a collection with optional filtering.

Query Parameters

Add Collection Entry

POST /api/v2/item-collections/{id}/entries

Adds a line item to a collection.

Request Body

Response

Returns the created entry with status 201 Created.

Update Collection Entry

PUT /api/v2/item-collections/{id}/entries/{entry_id}

Updates an existing entry. The item_collection_id cannot be changed.

Response

Returns the updated entry with status 202 Accepted.

Delete Collection Entry

DELETE /api/v2/item-collections/{id}/entries/{entry_id}

Permanently deletes an entry from the collection.

Response

Returns the deleted entry with status 200 OK.

Note: The backend currently returns 201 Created for this endpoint, which is a known quirk. This documentation uses 200 OK as the semantically correct status for a DELETE operation.

Unit Endpoints

Units represent standard measurement units (e.g., hours, pieces, kilograms) following the UN/ECE Recommendation 20/21 codes.

List Units

GET /api/v2/units

Retrieves all available units of measure.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "symbol": "stk",
      "un_ece_rec_20_code": "C62",
      "un_ece_rec_21_code": null,
      "description": "One (piece)"
    },
    {
      "id": 5,
      "symbol": "timer",
      "un_ece_rec_20_code": "HUR",
      "un_ece_rec_21_code": null,
      "description": "Hours"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 2
  }
}

Get Unit

GET /api/v2/units/{id}

Retrieves a specific unit by ID.

Response

{
  "id": 5,
  "symbol": "timer",
  "un_ece_rec_20_code": "HUR",
  "un_ece_rec_21_code": null,
  "description": "Hours"
}

Item Types

Collection Types

Error Responses

Business Rules

1. Items are scoped to a specific client account
2. Users must have access to the client account to manage its items
3. The client_account_id cannot be changed after item creation
4. Deleting an item deactivates it rather than removing it, preserving historical data
5. Item collections use cascade deletion: removing a collection also removes all its entries
6. Units are system-wide and read-only

Common Use Cases

1. Product catalog - Maintain a list of products and services with default pricing
2. Invoice templates - Create reusable collections of line items for recurring invoices
3. Recurring billing - Set up collection entries with recurring schedules and terms
4. Multi-currency pricing - Specify currency codes on collection entries for international invoicing