Create and manage products

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 receivables.

Roles and permissions

When making API calls with an entity user token, keep in mind that:

  • The /products* endpoints require a role with the product permission.
  • The /measure_units* endpoints require a role with the receivable permission.

When using a partner-level token, no extra permissions are needed.

Manage measure units

A measure unit is the standard unit used to measure the quantity of a product. Depending on the entity’s country, measure units may be required for products before a receivable can be issued. Examples: meters, kilograms, pieces, hours. To create a measure unit, call POST /measure_units:

1curl -X POST 'https://api.sandbox.monite.com/v1/measure_units' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "name": "kg",
8       "description": "Kilogram"
9     }'

The successful response contains the id property that acts as an identifier for the created measure unit. This ID is required to assign a measure unit to a product.

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

One measure unit per product

Each product can only be associated with a single measure unit. If a specific product is available in kilograms and tonnes, you can create multiple products, one for 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}.

Manage products

Create a product

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, and other necessary information.

Product pricing

Product prices 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).

1curl -X POST 'https://api.sandbox.monite.com/v1/products' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "name": "Ice cream",
8       "type": "product",
9       "description": "A delicious vanilla ice cream",
10       "price": {
11         "currency": "EUR",
12         "value": 1500
13       },
14       "measure_unit_id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
15       "smallest_amount": 1
16     }'

The successful response includes the id of the created product:

1{
2  "id": "8755c86a-d630-4920-b6fd-fd2917d87dfb",
3  ...
4}

Product currencies on invoices

Currencies of products added as line items on an invoice must always match the invoice’s base currency. You can create products and services in multiple currencies to match the invoice’s base currency.

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}.