Create and 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 must also create the related measure units.
Roles and permissions
When making API calls with an entity user token, keep in mind that:
- The
/products*
endpoints require a role with theproduct
permission.- The
/measure_units*
endpoints require a role with thereceivable
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. 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-06-04' \
-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
property that acts as an identifier for the created measure unit. You will need this id
in subsequent API calls.
{
"id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
...
}
One product per measure unit
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}
.
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.
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). For more information, see minor units.
curl -X POST 'https://api.sandbox.monite.com/v1/products' \
-H 'X-Monite-Version: 2023-06-04' \
-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¤cy=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}
.
Updated 19 days ago