> For the complete documentation index, see [llms.txt](https://docs.fulfillmenttools.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/measurement-units.md).

# Measurement units

In fulfillmenttools, each article (identified by a tenantArticleId in a facility) is tracked per unit. A unit commonly represents a physical unit, like `g` or `kg,` or for countable goods, something like `pieces` or `pcs`. Since each product is kept in a single measurement unit, operations like adding or moving stock don't need to validate or convert units between stock items.

Units can be defined in the `measurementUnitKey` in the [listing](/documentation/by-pillar/global-inventory-hub/listing.md). The defined key will be displayed in the clients, for example, during picking if no measurement unit is defined for the key. It's not required to define units for articles. When no unit is set in the [listing](/documentation/by-pillar/global-inventory-hub/listing.md), no validation occurs, and our clients will default to localized versions of `pieces`.

You might want to change the `measurementUnitKey` for items that are sold by weight, for example, fruits and vegetables, or by length, for example, fabric. 

## Implementation

To create a new measurement unit for your tenant, use the endpoint below:

{% tabs %}
{% tab title="Endpoint" %}

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/measurementunits
```

{% endtab %}

{% tab title="Request" %}

```json
{
    "key": "KILOGRAM",
    "nameLocalized": { "en_US": "KILO" },
    "abbreviationLocalized": { "en_US": "kg" },
    "requiresMeasurement": true
}
```

{% endtab %}
{% endtabs %}

To then use this measurement unit in a listing, use the endpoint below:

{% tabs %}
{% tab title="Endpoint" %}

```http
PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{FACILITY_ID}/listings
```

{% endtab %}

{% tab title="Request" %}

```json
{
    "listings": [
        {
            "tenantArticleId": "Bison-food",
            "price": 50.00,
            "title": "Bison food",
            "scannableCodes": ["Bison-food"],
            "measurementUnitKey": "KILOGRAM"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

The measurement unit will then display in the clients for that listing.

<figure><img src="/files/45PDMPFJbY60fQZyAHoZ" alt=""><figcaption></figcaption></figure>

## Unit validation in inbound processes

When using the [inbound process](/documentation/by-pillar/global-inventory-hub/inbound-process.md), it's recommended to define units for each product in its respective facility listing.

Since no automatic conversion between units occurs, it's essential to specify the correct unit when new goods are accepted into the system. This eliminates a common source of critical errors in stock levels.

When a `measurementUnitKey` is set on the corresponding [listing](/documentation/by-pillar/global-inventory-hub/listing.md), each new line item in the purchase order's requested items and the receipt's received items is validated against it. All quantities must match the unit of the listing.

{% hint style="info" %}
Attention: When creating an `inboundProcess` with a `purchaseOrder` with unit `xyz` and changing the `listing.measurementUnitKey` to something else (`qwe`), the `inboundProcess.purchaseOrder` must now be patched/replaced to reflect the correct unit again before a receipt can be created in the Inventory app.&#x20;

This is intentional and ensures consistency in new stock levels at the facility. In general, it's not advisable to change a product's unit in a facility without careful consideration. In some cases, it may be desired to start with no unit on the `listing` (= no validation) and transition to stricter rules later.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/measurement-units.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.