Services

Services are catalog entities non-physically provided to clients.

Base URL: https://api.planadoapp.com/v2/catalog/services

List services

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/services | jq
{
  "services": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Delivery",
      "description": "With bringing to the door",
      "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
      "currency": "eur",
      "external_id": "delivery",
      "price_default": "15.99",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Faucet installation",
      "description": null,
      "category_uuid": null,
      "currency": "eur",
      "external_id": null,
      "price_default": "10.0",
      "archived": false
    },
    ...
  ]
}

Table 1. Fields of `services` elements
Field	Type	JSON type	Can be `null`	Description
`uuid`	UUID	String	No	Unique identifier
`name`	String	String	No	Service name
`description`	String	String	Yes	Service description
`category_uuid`	UUID	String	Yes	Category UUID
`currency`	String	String	No	ISO 4217 code in lower case
`external_id`	String	String	Yes	External ID
`price_default`	Number	Number	Yes	Price
`archived`	Boolean	Boolean	No	Whether the service is archived or not

Create service

To create a service, send a POST request to https://api.planadoapp.com/v2/catalog/services.

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/services \
       --data @- <<EOF | jq
{
  "name": "Insurance",
  "category": {
    "name": "Customer service"
  },
  "price_default": "4.0"
}
EOF
{
  "service_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}

Service price currency is taken from your account settings.

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

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	Service name. Limited to 250 characters
`category`	Category	Object	No	Yes	Service category
`external_id`	String	String	No	Yes	External ID
`description`	String	String	No	Yes	Service description. Limited to 500 characters
`price_default`	Float	Float	No	Yes	Price

name

String

Yes

Service name. Limited to 250 characters

category

Get service

Service can be retrieved by uuid or external_id.

Using uuid

$ curl -H "Authorization: Bearer api-key" \
  https://api.planadoapp.com/v2/catalog/services/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "service": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Delivery",
    "description": "With bringing to the door",
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "currency": "eur",
    "external_id": "delivery",
    "price_default": "15.99",
    "archived": false
  }
}

Using external_id

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/services/delivery | jq
{
  "service": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Delivery",
    "description": "With bringing to the door",
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "currency": "eur",
    "external_id": "delivery",
    "price_default": "15.99",
    "archived": false
  }
}

Update service

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

Updating description of an existing service

$ curl --data "{\"description\":null}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/services/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "service_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	Service name. Limited to 250 characters
`category`	Category	Object	No	Yes	Service category
`description`	String	String	No	Yes	Service description. Limited to 500 characters
`price_default`	Float	Float	No	Yes	Price

name

String

Service name. Limited to 250 characters

category

Remove service

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

Removing by uuid

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

Service archivation

Services can be archived and unarchived. Archived services are hidden in interface. Send corresponding POST request to https://api.planadoapp.com/v2/catalog/services/:service_id/archive or https://api.planadoapp.com/v2/catalog/services/:service_id/unarchive.

Archiving by uuid

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