Cost Centres

Manage cost centres for budget tracking and financial allocation.

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

Returns a paginated list of cost centres in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by name or description
sortBy	string	name	Sort field: 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": "clx6t7u8v9w0x1y2",
      "name": "R&D",
      "code": "CC-100",
      "description": "Research and development",
      "costCategory": "engineering",
      "color": "#6B7280",
      "isActive": true,
      "sortOrder": 0,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx1e2n3g4r5o0t6",
      "name": "Sales & Marketing",
      "code": "CC-200",
      "description": "Revenue generation and brand awareness",
      "costCategory": "sales",
      "color": "#3B82F6",
      "isActive": true,
      "sortOrder": 1,
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 5,
    "hasNextPage": false
  }
}

---

Get Cost Centre

GET /org/:orgId/cost-centres/:id

Returns a single cost centre by ID.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/cost-centres/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "R&D",
    "code": "CC-100",
    "description": "Research and development",
    "costCategory": "engineering",
    "color": "#6B7280",
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2025-11-20T14:00:00Z"
  }
}

---

Create Cost Centre

POST /org/:orgId/cost-centres

Creates a new cost centre.

Request Body

{
  "name": "R&D",
  "code": "CC-100",
  "description": "Research and development",
  "costCategory": "engineering"
}

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",
    "costCategory": "engineering"
  }'

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "name": "R&D",
    "code": "CC-100",
    "description": "Research and development",
    "costCategory": "engineering",
    "color": "#6B7280",
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Cost Centre

PATCH /org/:orgId/cost-centres/:id

Updates one or more fields on an existing cost centre. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/cost-centres/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research & Development",
    "description": "All R&D engineering and research activities."
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "Research & Development",
    "code": "CC-100",
    "description": "All R&D engineering and research activities.",
    "costCategory": "engineering",
    "color": "#6B7280",
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Cost Centre

DELETE /org/:orgId/cost-centres/:id

Deletes a cost centre. Cost centres that are actively assigned to teams or budget line items cannot be deleted until those references are removed.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/cost-centres/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "deleted": true
  }
}

Status: 200 OK

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Cost centre name
code	string	No	Short code for reporting (e.g., "CC-100")
description	string	No	Cost centre description
costCategory	string	No	Category label (e.g., "engineering", "sales")
color	string	No	Hex color for UI display (default: "#6B7280")
isActive	boolean	No	Whether the cost centre is active (default: true)
sortOrder	integer	No	Display sort order (default: 0)
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)