Manage products

Learn how to manage the goods, materials, and services that can be listed in invoices.

Overview

The Product object represents the specific services, materials, or physical or digital goods sold by an entity. An entity must have products configured in order to create outgoing invoices.

Before creating a product, you also need to create the related measure units.

Manage measure units

A measure unit is the standard unit used to measure the quantity of a product. Examples: meters, kilograms, pieces, hours.

To create a measure unit, call POST /measure_units:

curl -X POST 'https://api.sandbox.monite.com/v1/measure_units' \
     -H 'X-Monite-Version: 2023-02-07' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "kg",
       "description": "Kilogram"
     }'

The successful response contains the id assigned to the created measure unit. You will need this id in subsequent API calls.

{
  "id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
  ...
}

Each product can be associated with a single measure unit only. If a specific product is available, say, in both kilograms and tonnes, you can create multiple products, one per each measure unit.

List all measure units

To get a list of all created measure units, call GET /measure_units.

Retrieve a measure unit

To get information about a specific measure unit, call the GET /measure_units/{unit_id}.

Update a measure unit

To update a specific measure unit, call the PATCH /measure_units/{unit_id}.

Delete a measure unit

To delete an existing measure unit, call the DELETE /measure_units/{unit_id}.

Create a product

After you created a measure unit, you can create a new product by calling POST /products. The request body needs to contain the product name, type (product or service), price per unit, measure unit ID, and other necessary information.

The price must be specified in the minor units of currency, that is, the smallest currency unit available such as cent or penny. For example, 15 EUR is represented as 1500 (in euro cents).

curl -X POST 'https://api.sandbox.monite.com/v1/products' \
     -H 'X-Monite-Version: 2023-02-07' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Ice cream",
       "type": "product",
       "description": "A delicious vanilla ice cream",
       "price": {
         "currency": "EUR",
         "value": 1500
       },
       "measure_unit_id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
       "smallest_amount": 1
     }'

The successful response includes the id of the created product:

{
  "id": "8755c86a-d630-4920-b6fd-fd2917d87dfb",
  ...
}

List all products

To get a list of all created products, call GET /products. You can sort the products by name, and filter them by name, price, measure unit, and other fields. For a full list of available sort and filter parameters, see the description of the GET /products endpoint.

Some examples:

  • GET /products?name__icontains=shirt - get all products with "shirt" in the name (case-insensitive).
  • GET /products?price__lte=10000&currency=EUR - get all products whose price is €100 or less.
  • GET /products?created_at__gte=2022-01-01T00%3A00%3A00 - get all products added on or after January 1, 2022.
  • GET /products?measure_unit_id=e3ef0046-450f-40e5-b2f1-7fcfefcff450 - get all products that use a specific measure unit (such as kilograms or pieces).

Retrieve a product

To get information about a specific product, call GET /products/{product_id}.

Edit a product

To edit an existing product, call PATCH /products/{product_id} .

Delete a product

To delete an existing product, call DELETE /product/{product_id}.