Units

Every product must have a measurement unit. Unit operations are listed below.

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

List units

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products/units | jq
{
  "units": [
    {
      "uuid": "f6672a42-77f5-42ce-a88b-c219525f87f4",
      "name": "kilogram",
      "code": "kg",
      "external_id": "unit-kg",
      "archived": false
    },
    {
      "uuid": "5051d58c-0030-498b-a5c2-41b13ecc0a9c",
      "name": "mile",
      "code": "ml",
      "external_id": null,
      "archived": true
    },
    ...
  ]
}
Table 1. Fields of units elements
Field Type JSON type Can be null Description

uuid

UUID

String

No

Unique identifier

name

String

String

No

Unit name

code

String

String

No

Unit short name

external_id

String

String

Yes

External ID

archived

Boolean

Boolean

No

Whether the unit is archived or not

Create unit

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

$ curl --data "{\"name\":\"kilogram\",\"code\":\"kg\"}" \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products/units | jq
{
  "unit_uuid": "72e522d5-632c-44a0-9999-65de8389bb8b"
}

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

Request schema

Field Type JSON type Required Can be null Description

name

String

String

Yes

No

Unit name. Limited to 250 characters

code

String

String

Yes

No

Unit short name. Limited to 50 characters

external_id

String

String

No

No

External ID

Get unit

Units can be retrieved by uuid or external_id.

Using uuid
$ curl -H "Authorization: Bearer api-key" \
  https://api.planadoapp.com/v2/catalog/products/units/9a009fdd-31c7-4195-8a6a-4c3cdea28781 | jq
{
  "unit": {
    "uuid": "9a009fdd-31c7-4195-8a6a-4c3cdea28781",
    "name": "kilogram",
    "code": "kg",
    "external_id": "unit-kg",
    "archived": false
  }
}
Using external_id
$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products/units/unit-kg | jq
{
  "unit": {
    "uuid": "9a009fdd-31c7-4195-8a6a-4c3cdea28781",
    "name": "kilogram",
    "code": "kg",
    "external_id": "unit-kg",
    "archived": false
  }
}

Update unit

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

Updating name of an existing unit
$ curl --data "{\"name\":\"Kilo\"}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products/units/9a009fdd-31c7-4195-8a6a-4c3cdea28781 | jq
{
  "unit_uuid": "9a009fdd-31c7-4195-8a6a-4c3cdea28781"
}

Request schema

Field Type JSON type Required Can be null Description

name

String

String

No

No

Unit name. Limited to 250 characters

code

String

String

No

No

Unit short name. Limited to 50 characters

Remove unit

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

Removing by uuid
$ curl -H "Authorization: Bearer api-key" -X DELETE https://api.planadoapp.com/v2/catalog/products/units/5051d58c-0030-498b-a5c2-41b13ecc0a9c | jq
{
  "message": "Performed"
}

Unit archivation

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

Archiving by uuid
$ curl -H "Authorization: Bearer api-key" -X POST "https://api.planadoapp.com/v2/catalog/products/units/9a009fdd-31c7-4195-8a6a-4c3cdea28781/archive" | jq
{
  "unit_uuid": "9a009fdd-31c7-4195-8a6a-4c3cdea28781"
}