Products

Products are catalog entities physically provided to clients. To accurately track their usage each product must have a measurement unit.

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

List products

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products | jq
{
  "products": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Cable (twisted pair)",
      "description": "FFTP"
      "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
      "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
      "currency": "eur",
      "external_id": "cable-tp",
      "gtin": null,
      "price_default": "1.05",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Plastic cap",
      "description": null,
      "category_uuid": null,
      "unit_uuid": "8204378f-b7ad-410c-b5af-c747bddb5905",
      "currency": "eur",
      "external_id": "cap",
      "gtin": "96788301",
      "price_default": "0.5",
      "archived": false
    },
    ...
  ]
}

Table 1. Fields of `products` elements
Field	Type	JSON type	Can be `null`	Description
`uuid`	UUID	String	No	Unique identifier
`name`	String	String	No	Product name
`description`	String	String	Yes	Product description
`category_uuid`	UUID	String	Yes	Category UUID
`unit_uuid`	UUID	String	No	Unit UUID
`currency`	String	String	No	ISO 4217 code in lower case
`external_id`	String	String	Yes	External ID
`gtin`	String	String	Yes	Global Trade Item Number
`price_default`	Number	Number	Yes	Price
`archived`	Boolean	Boolean	No	Whether the product is archived or not

Create product

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

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products \
       --data @- <<EOF | jq
{
  "name": "Cable",
  "unit": {
    "name": "Meter"
  },
  "price_default": "1.05"
}
EOF
{
  "product_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}

Product price currency is taken from your account settings.

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

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	Product name. Limited to 250 characters
`unit`	Unit	Object	Yes	No	Product unit
`category`	Category	Object	No	Yes	Product category
`external_id`	String	String	No	Yes	External ID
`description`	String	String	No	Yes	Product description. Limited to 500 characters
`price_default`	Float	Float	No	Yes	Price
`gtin`	String	String	No	Yes	Global Trade Item Number

name

String

Yes

Product name. Limited to 250 characters

unit

Unit

Object

Yes

Product unit

category

Get product

Products can be retrieved by uuid or external_id.

Using uuid

$ curl -H "Authorization: Bearer api-key" \
  https://api.planadoapp.com/v2/catalog/products/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "product": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Cable (twisted pair)",
    "description": "FFTP"
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
    "currency": "eur",
    "external_id": "cable-tp",
    "gtin": null,
    "price_default": "100.0",
    "archived": false
  }
}

Using external_id

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products/cable-tp | jq
{
  "product": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Cable (twisted pair)",
    "description": "FFTP"
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
    "currency": "eur",
    "external_id": "cable-tp",
    "gtin": null,
    "price_default": "100.0",
    "archived": false
  }
}

Update product

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

Updating gtin of an existing product

$ curl --data "{\"gtin\":\"96788301\"}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "product_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	Product name. Limited to 250 characters
`unit`	Unit	Object	No	No	Product unit
`category`	Category	Object	No	Yes	Product category
`description`	String	String	No	Yes	Product description. Limited to 500 characters
`price_default`	Float	Float	No	Yes	Price
`gtin`	String	String	No	Yes	Global Trade Item Number

name

String

Product name. Limited to 250 characters

unit

Unit

Object

Product unit

category

Remove product

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

Removing by uuid

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

Product archivation

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

Archiving by uuid

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