CustomerCategory

A customer category: the hand-maintained taxonomy customers are grouped by, used for segmentation and reporting.

Summary view: CustomerCategoryList, 7 fields. What a list returns by default.
Detail view: CustomerCategory, 7 fields. The default for a single read and for every write.
Read with: api:read:customer_categoriesandcustomer_categories::read
Write with: api:write:customer_categoriesandcustomer_categories::create

Example

detail view

{
  "id": 1,
  "name": "Enterprise",
  "description": "Accounts over 500 seats.",
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "customers_count": 1,
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "customers": "https://<your-url>/api/v2/work-items/1"
  }
}

Deleting one un-categorises its customers rather than blocking.

Used by

GETList customer categories/customer-categoriesCustomerCategoryList

POSTCreate a customer category/customer-categoriesCustomerCategory

GETRead a customer category/customer-categories/{customer_category}CustomerCategory

PATCHUpdate a customer category/customer-categories/{customer_category}CustomerCategory

Fields

Detail only: Only in the detail view.
Only with include: Only when you ask for it with include.
Server-assigned: Set by plnnrly, never by a request.

idinteger

Unique identifier.

namestring≤ 255

Category name as shown in the UI, e.g. Enterprise.

descriptionstring or nullMultiline

Free-text note on what belongs in this category.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

customers_countinteger≥ 0

Number of customers in this category.

linksCustomerCategoryLinks

Show 2 child fields

links.selfurl

The canonical URI of this record.

links.customersurl

Customers in this category.

Variants

CustomerCategoryList 7 fields

What a collection returns, and what ?view=summary returns on a single record.

The same fields as the detail object.

CustomerCategorySummary 2 fields

The embedded form: what you get when another resource carries this one and you did not include it.

Leaves out: description, created_at, updated_at, customers_count, links

CustomerCategoryLinks 2 fields

The links object on this resource.

Keys: self, customers

Something wrong or missing on this page? Tell us