Categories

Categories are used to group products and services.

Products' and services' categories can’t intersect. They use separate endpoints.

Categories are hierarchical. Category can have a parent category. That tree structure supports up to 3 levels.

Base URLs: https://api.planadoapp.com/v2/catalog/products/categories and https://api.planadoapp.com/v2/catalog/services/categories

List categories

List service categories

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/services/categories | jq
{
  "categories": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Deliveries",
      "description": null,
      "external_id": "deliveries",
      "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Installations",
      "description": "Outdoors",
      "external_id": null,
      "parent_uuid": null,
      "archived": false
    },
    ...
  ]
}

Table 1. Fields of `categories` elements
Field	Type	JSON type	Can be `null`	Description
`uuid`	UUID	String	No	Unique identifier
`name`	String	String	No	Category name
`description`	String	String	Yes	Category description
`external_id`	String	String	Yes	External ID
`parent_uuid`	UUID	String	Yes	Parent category UUID
`archived`	Boolean	Boolean	No	Whether the category is archived or not

Create category

To create a category, send a POST request.

Creating product category

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products/categories \
       --data @- <<EOF | jq
{
  "name": "Cables",
  "parent": {
    "name": "Materials"
  }
}
EOF
{
  "category_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}

In response, the API returns the uuid value of the newly created category.

Request schema

Field Type JSON type Required Can be null Description

Field	Type	JSON type	Required	Can be `null`	Description
`name`	String	String	Yes	No	Category name. Limited to 250 characters
`parent`	Category	Object	No	Yes	Parent category
`external_id`	String	String	No	Yes	External ID
`description`	String	String	No	Yes	Category description. Limited to 500 characters

name

String

Yes

Category name. Limited to 250 characters

parent

Get category

Category can be retrieved by uuid or external_id.

Using uuid

$ curl -H "Authorization: Bearer api-key" \
  https://api.planadoapp.com/v2/catalog/services/categories/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "category": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Deliveries",
    "description": null,
    "external_id": "deliveries",
    "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
    "archived": false
  }
}

Using external_id

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/services/categories/deliveries | jq
{
  "category": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Deliveries",
    "description": null,
    "external_id": "deliveries",
    "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
    "archived": false
  }
}

Update category

To update a category send a PATCH request to https://api.planadoapp.com/v2/catalog/services/categories/:category_id. Here :category_id is the uuid or the external_id value of the category.

Updating description of an existing category

$ curl --data "{\"description\":\"Free\"}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/services/categories/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "category_uuid": "0a7b6f74-9bd3-434f-8588-c677bac93d4c"
}

Request schema

Field Type JSON type Required Can be null Description

Field	Type	JSON type	Required	Can be `null`	Description
`name`	String	String	No	No	Category name. Limited to 250 characters
`parent`	Category	Object	No	Yes	Parent category
`description`	String	String	No	Yes	Category description. Limited to 500 characters

name

String

Category name. Limited to 250 characters

parent

Remove category

Send a DELETE request with uuid or external_id to remove a category.

Removing by uuid

$ curl -H "Authorization: Bearer api-key" -X DELETE https://api.planadoapp.com/v2/catalog/products/categories/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "message": "Performed"
}

Category archivation

Categories can be archived and unarchived. Archived categories are hidden in interface. Send corresponding POST request to https://api.planadoapp.com/v2/catalog/services/categories/:category_id/archive or https://api.planadoapp.com/v2/catalog/services/categories/:category_id/unarchive (replace services with products if needed).

Archiving by uuid

$ curl -H "Authorization: Bearer api-key" -X POST "https://api.planadoapp.com/v2/catalog/services/categories/b8994bf9-e46a-4f4f-9747-6a9f19b5157e/archive" | jq
{
  "category_uuid": "b8994bf9-e46a-4f4f-9747-6a9f19b5157e"
}