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.
When making API calls with an entity user token, keep in mind that:
/products* endpoints require a role with the product permission./measure_units* endpoints require a role with the receivable permission.When using a partner-level token, no extra permissions are needed.
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:
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.
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.
To get a list of all created measure units, call GET /measure_units.
To get information about a specific measure unit, call the GET /measure_units/{unit_id}.
To update a specific measure unit, call the PATCH /measure_units/{unit_id}.
To delete an existing measure unit, call the DELETE /measure_units/{unit_id}.
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).
The successful response includes the id of the created product:
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.
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).To find invoices, quotes, or credit notes that include a specific product, use GET /receivables with the product_ids and product_ids__in filters.
product_ids is an AND filter and product_ids__in is an OR filter.
Spaces and line breaks have been added for readability only.
Find all invoices that include product A:
Find all invoices that include products A and B (among other products):
Find all invoices that include product A or product B:
To get information about a specific product, call GET /products/{product_id}.
To edit an existing product, call PATCH /products/{product_id} .
To delete an existing product, call DELETE /product/{product_id}.