# Unit Handling Tutorial

Unit handling defines, localizes, and converts measurement units (metric, imperial, USC, and custom) used across your catalog and calculations. It is tenant-scoped and acts as the source of truth for unit codes, names/symbols, base units, and conversion factors.

Unit handling integrates with the following services:

* **Price Service**:
  * Validates unit codes when creating or updating price models.
  * Converts units during price matching when the requested unit differs from the price model's unit.
* **Cart Service**:
  * Validates unit codes when adding or updating cart items.

{% hint style="success" %}
Changes to units propagate across the platform within \~5 minutes after create/update/delete operations.
{% endhint %}

## How to add a new unit

To add a new measurement unit to your configuration, send a request to the [Adding a new unit](https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-management#post-unit-handling-tenant-units) endpoint.

{% hint style="warning" %}
Unit names are localized. When creating a new unit, you can specify the unit name in two different ways — in one language or in multiple languages.

If you need more info on localization, see the [*Standard practices*](/api-references/standard-practices/translations.md) documentation.
{% endhint %}

{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}

{% content-ref url="/pages/NNgvoyR5R4wyK5zIt7Z6" %}
[API Reference](/api-references/api-guides/configuration/unit-handling-service/api-reference.md)
{% endcontent-ref %}

```bash
curl -L 
  --request POST 
  --url 'https://api.emporix.io/unit-handling/{tenant}/units' 
  --header 'Content-Language: fr' 
  --header 'Content-Type: application/json' 
  --data '{
    "code": "kg",
    "name": "kilogram",
    "type": "mass",
    "baseUnit": true,
    "symbol": "kg",
    "factor": 1
  }'
```

## How to convert units

You can convert between any measurement units that share the same base unit, such as kilograms to grams, or centimeters to meters.

To convert between units, send a request to the [Converting units ](https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-conversion#put-unit-handling-tenant-units-convert-unit-commands)endpoint.

{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}

{% content-ref url="/pages/NNgvoyR5R4wyK5zIt7Z6" %}
[API Reference](/api-references/api-guides/configuration/unit-handling-service/api-reference.md)
{% endcontent-ref %}

<pre class="language-bash"><code class="lang-bash">curl -L 
<strong>  --request PUT 
</strong>  --url 'https://api.emporix.io/unit-handling/{tenant}/units/convert-unit-commands' 
  --header 'Content-Type: application/json' 
  --data '{
    "commandUuid": "550e8400-e29b-41d4-a716-446655440000",
    "input": {
      "sourceUnitAmount": 100,
      "sourceUnit": "g",
      "targetUnit": "kg"
    }
  }'
</code></pre>

## Using unit handling with price service

The Price Service uses unit codes for measurement-based pricing, for example, per kg, per L.

When displaying per-unit prices, the Unit Handling is used to calculate conversion factors or to convert quantities before computing or presenting prices.

### Validating units in price models

When creating or updating a price model, the `unitCode` in the `measurementUnit` field must exist in Unit Handling. The Price Service validates this by checking if the unit exists.

**Example: Creating a price model with unit validation**

Before creating a price model with `unitCode: "kg"`, first verify if the unit exists, by sending a request to the [Finding units by filters with sorting and paging](https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-management#get-unit-handling-tenant-units) endpoint.

```bash
curl -L 
  --url 'https://api.emporix.io/unit-handling/{tenant}/units' 
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  --header 'Accept: */*'
```

If the unit exists, proceed with creating the price model:

```bash
curl -L 
  --request POST 
  --url 'https://api.emporix.io/price/{tenant}/priceModels' 
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  --header 'Content-Type: application/json' 
  --data '{
    "includesTax": true,
    "includesMarkup": true,
    "name": "Tiered pricing - per kilogram",
    "measurementUnit": {
      "quantity": 1,
      "unitCode": "kg"
    },
    "tierDefinition": {
      "tierType": "TIERED",
      "tiers": [
        {
          "minQuantity": {
            "quantity": 0,
            "unitCode": "kg"
          }
        }
      ]
    }
  }'
```

If the unit doesn't exist, create it first using the Unit Handling Service.

### Converting units in price matching

When matching prices, if the requested `unitCode` differs from the price model's unit, the system uses Unit Handling to convert the price to the requested unit.

**Example: Matching prices with unit conversion**

Request a price match for 10 kg, but the price model uses grams:

```json
{
  "targetCurrency": "EUR",
  "siteCode": "1111",
  "targetLocation": {
    "countryCode": "DE"
  },
  "items": [
    {
      "itemId": {
        "itemType": "PRODUCT",
        "id": "5f5a3a365bac380024b93c45"
      },
      "quantity": {
        "quantity": 10,
        "unitCode": "kg"
      }
    }
  ]
}
```

If the price model's `measurementUnit.unitCode` is `g` but you request `kg`, the Price Service internally calls the [Converting a unit](https://api.emporix.io/unit-handling/{tenant}/units/convert-unit-commands) enpoint:

```bash
curl -L 
  --request PUT 
  --url 'https://api.emporix.io/unit-handling/{tenant}/units/convert-unit-commands' 
  --header 'Content-Type: application/json' 
  --data '{
    "commandUuid": "83ddc478-89d7-48e1-8b6c-527f4c67fb56",
    "input": {
      "sourceUnitAmount": 10,
      "sourceUnit": "kg",
      "targetUnit": "g"
    }
  }'
```

The matched price response includes the converted quantity:

```json
{
  "quantity": {
    "quantity": 10000,
    "unitCode": "g"
  },
  "originalValue": 13.55,
  "effectiveValue": 13.55
}
```

{% content-ref url="/pages/aOAE7Wf4uf47InJyAs4h" %}
[API Reference](/api-references/api-guides/prices-and-taxes/price-service/api-reference.md)
{% endcontent-ref %}

## Validating units in cart items

When adding or updating cart items, the `unitCode` in `item.unitPrice.measurementUnit.unitCode` must exist in Unit Handling. The Cart Service validates this by checking if the unit exists.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/unit-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.