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. 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, 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:

Endpoint

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

Request

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

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

Endpoint

PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{YOUR_FACILITY_ID}/listings

Request

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

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

Unit validation in inbound processes

When using the inbound process, 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, 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.

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.

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.