Cost categories#

Manage reusable organization-owned cost categories for spend tracking and reporting.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/cost-categories#

List reusable cost categories with usage counts and recorded spend.

bash

GET /v1/cost-categories?page_index=0&page_size=25&organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/cost-categories#

Create a reusable organization-owned cost category while adding or editing costs.

bash

POST /v1/cost-categories
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
name	`string`	Required	Reusable cost category name.

Response#

Returns { data, _meta } with the result.

PATCH /v1/cost-categories/:id#

Update a reusable cost category name across every cost that uses it.

bash

PATCH /v1/cost-categories/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).
name	`string`	Required

Response#

Returns { data, _meta } with the result.

DELETE /v1/cost-categories/:id#

Permanently delete an unused cost category; referenced categories are blocked.

bash

DELETE /v1/cost-categories/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.