> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage products

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

The **Product** object represents the specific services, materials, or physical or digital goods sold by an [organization](/finops/guides/organizations/index). An organization must have products configured in order to create outgoing receivables.

## Roles and permissions

When making API calls with an [organization user token](/finops/guides/organizations/users#get-organization-user-token), keep in mind that:

* The `/products*` endpoints require a [role](/finops/guides/organizations/users#create-role) with the `product` permission.
* The `/measure-units*` endpoints require a role with the `receivable` permission.

When using a [partner-level token](/finops/guides/authentication/client-credentials), 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 organization'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`](/finops/reference/openapi/measure-units/post-measure-units):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/measure-units' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_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. This ID is required to assign a measure unit to a product.

```json lines theme={null}
{
  "id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
  ...
}
```

<Info>
  **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.
</Info>

### List all measure units

To get a list of all created measure units, call [`GET /measure-units`](/finops/reference/openapi/measure-units/get-measure-units).

### Retrieve a measure unit

To get information about a specific measure unit, call the [`GET /measure-units/{unit_id}`](/finops/reference/openapi/measure-units/get-measure-units-id).

### Update a measure unit

To update a specific measure unit, call the [`PATCH /measure-units/{unit_id}`](/finops/reference/openapi/measure-units/patch-measure-units-id).

### Delete a measure unit

To delete an existing measure unit, call the [`DELETE /measure-units/{unit_id}`](/finops/reference/openapi/measure-units/delete-measure-units-id).

## Manage products

### Create a product

You can create a new product by calling [`POST /products`](/finops/reference/openapi/products/post-products). The request body needs to contain the product name, type (`product` or `service`), price per unit, and other necessary information.

<Info>
  **Product pricing**

  Product prices must be specified in the [minor units](/finops/support/currencies) of currency, that is, the smallest currency unit available such as cent or penny. For example, 15 USD is represented as 1500 (in cents).
</Info>

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/products' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Ice cream",
       "type": "product",
       "description": "A delicious vanilla ice cream",
       "price": {
         "currency": "USD",
         "value": 1500
       },
       "measure_unit_id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
       "smallest_amount": 1
     }'
```

The successful response includes the `id` of the created product:

```json lines theme={null}
{
  "id": "8755c86a-d630-4920-b6fd-fd2917d87dfb",
  ...
}
```

<Info>
  **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.
</Info>

### List all products

To get a list of all created products, call [`GET /products`](/finops/reference/openapi/products/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`](/finops/reference/openapi/products/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=USD` - 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](#manage-measure-units) (such as kilograms or pieces).

### Find receivables that include a specific product

To find invoices, quotes, or credit notes that include a specific product, use [`GET /receivables`](/finops/reference/openapi/receivables/get-receivables) with the [`product_ids`](/finops/reference/openapi/receivables/get-receivables#request.query.product_ids.product_ids) and [`product_ids__in`](/finops/reference/openapi/receivables/get-receivables#request.query.product_ids.product_ids) filters. `product_ids` is an AND filter and `product_ids__in` is an OR filter.

#### Examples

<Info>Spaces and line breaks have been added for readability only.</Info>

Find all invoices that include product A:

```lines theme={null}
GET /receivables
    ? type = invoice
    & product_ids = <productA>
```

Find all invoices that include products A and B (among other products):

```lines theme={null}
GET /receivables
    ? type = invoice
    & product_ids = <productA>
    & product_ids = <productB>
```

Find all invoices that include product A or product B:

```lines theme={null}
GET /receivables
    ? type = invoice
    & product_ids__in = <productA>
    & product_ids__in = <productB>
```

### Retrieve a product

To get information about a specific product, call [`GET /products/{product_id}`](/finops/reference/openapi/products/get-products-id).

### Edit a product

To edit an existing product, call [`PATCH /products/{product_id}`](/finops/reference/openapi/products/patch-products-id) .

### Delete a product

To delete an existing product, call [`DELETE /product/{product_id}`](/finops/reference/openapi/products/delete-products-id).