# Unit Conversion

Master data for converting units. Workist can recognise units and automatically convert them to other quantities. To do this, Workist requires a list of conversion quotients.

:::warning
If unit conversion is to be used in Workist, the `sales_units` and `order_units` in the article list become mandatory! → [Article Master Data](/en/docs/master-data/articles.md)
:::

## Column Description

> **Required:** Workist cannot use the record without this column. **Recommended:** significantly improves recognition. The import itself does not check columns: if a column is missing, the field stays empty.

| # | Field Name | Status | Description |
|---|----------|--------|--------------|
| 1 | `partition_id` | <span class="status-optional">Optional</span> | `client_id1` of the customer the conversion applies to. Only takes effect if partition-specific unit conversion is enabled in the channel. If Workist finds no conversion for the customer, it uses the conversions without a `partition_id`. |
| 2 | `article_id` | <span class="status-required">Required</span> | Article number. Must be the same number as `article_id1` in the article master data. Workist always looks up conversions for a specific article number. |
| 3 | `source_unit` | <span class="status-required">Required</span> | Source unit of the conversion (the order unit) |
| 4 | `target_unit` | <span class="status-required">Required</span> | Target unit of the conversion (the sales unit) |
| 5 | `conversion_quotient` | <span class="status-required">Required</span> | Conversion quotient (often specified as a factor in other systems — here it must be 1/factor) |
| 6 | `extra_data` | <span class="status-optional">Optional</span> | Additional information as a JSON object, e.g. `{"Brand": "Sample"}`. Workist stores it with the record and shows it in the data explorer. By default, Workist does not use it for recognition. |

The import configuration does not show `article_id` as a row marked with `*`. Map the column anyway: Workist does not find conversions without an article number.

Keep in mind for the `conversion_quotient`:

- Every row needs a value, and the value needs a **point** as decimal separator (`0.125`, not `0,125`). Otherwise the import fails.
- If your system has a factor instead of a quotient, Workist can do the conversion during the import. Talk to your contact at Workist about it.

There may only be **one** row per article and source unit (and customer, if used). If Workist finds several conversions for the same combination, it cannot convert the line item.

## Format

> Columns that are not needed can be omitted from the data export.

Example file name: `conversion_factor_list.csv`

```csv
partition_id;article_id;source_unit;target_unit;conversion_quotient
;ART001;Karton;Packung;0.1
;ART002;Karton;Packung;0.05
K001;ART001;Karton;Packung;0.125
```

The example uses `;` as delimiter. Set the delimiter in the [import configuration](/en/docs/master-data/transformer-configuration.md); without a setting, Workist expects a comma.

In the example, a carton of `ART001` holds 10 packs (`0.1`), for customer `K001` 8 packs (`0.125`).

Via the API you send the same columns as a CSV file or as JSON. Endpoint: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/conversion_factors_imports_create), basics: [Using the Master Data API](/en/docs/api-documentation/master-data-api.md).

## Details on Unit Conversion

For unit conversions, Workist first needs to be configured for each available article to specify in which units it can be ordered and in which units it can be sold. At Workist we call these the available `order_units` and `sales_units` in the article master data.

### Adjustments in the Article Master Data

Example: configuring `order_units` and `sales_units` for a beer:
- `sales_units` is set to `["Flaschen"]` — Workist always converts this article to bottles in the output.
- `order_units` must be a list of all units in which customers can place orders, e.g. `["Kisten", "Sixpacks", "Flaschen"]`.

```csv
article_id1;description;article_id2;order_units;sales_units
123;Bier;000123;["Kisten","Sixpacks","Flaschen"];["Flaschen"]
abc;Orangensmoothie;000abc;["Flaschen"];["Flaschen"]
1234;Blaubeerwein;0001234;["Kisten","Flaschen"];["Flaschen"]
1122;Sprudelwasser;0001122;["Kisten","Flaschen"];["Flaschen"]
```

### Configuring the Conversion Master Data

The conversion is stored as a quotient. The `conversion_quotient` must contain:
- 1 bottle = 1/6 sixpack → `0.16666...`
- 1 bottle = 1/24 crate → `0.04166...`

```csv
article_id;source_unit;target_unit;conversion_quotient
123;Sixpacks;Flaschen;0.16666666666
123;Kisten;Flaschen;0.04166666666
1234;Kisten;Flaschen;0.125
1122;Kisten;Flaschen;0.08333333333
```

One entry in the master data is required for each article and `order_unit` combination (not for units that do not need to be converted, e.g. bottles to bottles).

When a customer orders 1 sixpack, Workist converts the output quantity to **6 bottles**.

### When No Conversion Fits

If a customer already orders in a sales unit, Workist does not convert. If Workist finds no matching conversion for another unit, it sets the article's first sales unit and flags quantity and unit for review in the assistance. You set how Workist rounds the result of a conversion in the channel configuration (see [unit conversion](/en/docs/channel-configuration/document-processing/document.md)).