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.

Changes to units propagate across the platform within ~5 minutes after create/update/delete operations.

How to add a new unit

To add a new measurement unit to your configuration, send a request to the Adding a new unit endpoint.

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 documentation.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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 endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request PUT 
  --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"
    }
  }'

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 endpoint.

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

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

curl -L 
  --request POST 
  --url 'https://api.emporix.io/price/{tenant}/priceModels' 
  --header 'Authorization: Bearer YOUR_OAUTH2_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:

{
  "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 enpoint:

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:

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

API Reference

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.