Cost Centres

Manage cost centres for budget tracking and financial allocation. Cost centres are used to categorise expenditure across the organization.

Cost Centre Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
name	string	Cost centre display name (e.g. "R&D", "Sales & Marketing").
code	string | null	Short accounting code for reporting (e.g. "CC-100").
description	string | null	Description of what this cost centre covers.
isActive	boolean	Whether this cost centre is active. Inactive cost centres are hidden from selection lists but preserved for historical data.
sortOrder	integer	Display ordering weight. Lower values appear first.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

---

Endpoints

Method	Path	Description
GET	/org/:orgId/cost-centres	List cost centres
GET	/org/:orgId/cost-centres/:id	Get cost centre
POST	/org/:orgId/cost-centres	Create cost centre
PATCH	/org/:orgId/cost-centres/:id	Update cost centre
DELETE	/org/:orgId/cost-centres/:id	Delete cost centre

---

List Cost Centres

GET /org/:orgId/cost-centres

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Free-text search by name or description.
sortBy	string	name	Field to sort by: name, code, sortOrder, createdAt.
sortDir	string	asc	asc or desc.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/cost-centres?sortBy=name&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "name": "R&D",
      "code": "CC-100",
      "description": "Research and development",
      "isActive": true,
      "sortOrder": 0,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 5,
    "hasNextPage": false
  }
}

---

Create Cost Centre

POST /org/:orgId/cost-centres

Create Request Body

Field	Type	Required	Description
name	string	Yes	Cost centre name.
code	string | null	No	Short accounting code.
description	string | null	No	Description.
costCategory	string | null	No	Category label (e.g. "engineering", "sales").
color	string	No	Hex colour for UI display. Default: "#6B7280".
isActive	boolean	No	Default: true.
sortOrder	integer	No	Display ordering. Default: 0.

Update Request Body

All fields from Create are accepted, all optional.

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/cost-centres" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "R&D",
    "code": "CC-100",
    "description": "Research and development"
  }'

Status: 201 Created

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [{ "field": "name", "message": "name is required" }],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Cost centre not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

---

Related Endpoints

• Teams -- Teams can be associated with cost centres.
• Projects -- Projects can be associated with cost centres via assignments.