# Article attributes

fulfillmenttools uses article `attributes` to customize processes and enhance the display of information in client applications.

{% hint style="warning" %}
**Attention:** Don't confuse `attributes` with [`customAttributes`](https://docs.fulfillmenttools.com/documentation/getting-started/custom-attributes).
{% endhint %}

**Example entry of the `attributes` model:**

```json
{
    "category": "descriptive",
    "type": "STRING",
    "priority": 100,
    "key": "Farbe", // This field is read-only
    "keyLocalized": {
        "de_DE": "Farbe",
        "en_US": "Color"
    },
    "value": "Blau",
    "valueLocalized": {
        "de_DE": "Blau",
        "en_US": "Blue"
    }
}
```

The `priority` property sorts the attributes in a client application. The allowed value ranges from 1 (highest priority) to 1000 (lowest priority). The default value is 1001.

## Supported categories

<table><thead><tr><th width="303">Category</th><th>Comment</th></tr></thead><tbody><tr><td><code>descriptive</code></td><td>The <code>key</code> and <code>value</code> are shown in fulfillmenttools clients, such as Backoffice. This category can enhance the displayed data to simplify data processing.</td></tr><tr><td><code>pickingSequence</code></td><td>Defines the sequence in which line items are ordered during picking.</td></tr><tr><td><code>miscellaneous</code> (default)</td><td>The fulfillmenttools clients don't currently use this category, except for the <code>BRAND</code> key.</td></tr><tr><td><code>customs</code></td><td>Includes keys such as <code>valuePerUnit</code>, <code>hsCode</code>, and <code>currency</code>. Other keys are also possible for this attribute.</td></tr><tr><td><code>insurance</code></td><td>Defines insurance-related data and can include keys such as <code>valuePerUnit</code> and <code>currency</code>.</td></tr><tr><td><code>shop</code></td><td>Defines the customer shop price and can include keys such as <code>valuePerUnit</code> and <code>currency</code>.</td></tr><tr><td><code>dimensions</code></td><td>Defines dimensions and includes keys such as <code>weightPerUnit</code>, <code>height</code>, <code>width</code>, and <code>length</code>. It's recommended to use the smallest unit as separators aren't permitted. Consistency in unit selection across all articles is required to enable meaningful comparisons.</td></tr><tr><td><code>salesPrice</code></td><td>Defines the price at which supplier facilities sell the listing to other facilities in the network.</td></tr></tbody></table>

{% hint style="info" %}
For the categories `customs`, `insurance`, `shop`, `salesPrice`, and `dimensions`, the `type` field is mandatory. The type can be `CURRENCY` ([ISO-4217](https://en.wikipedia.org/wiki/ISO_4217)), `NUMBER`, or `STRING`. For all other categories, the `type` field is optional.
{% endhint %}

## Special categories

### Category dimensions

<table data-full-width="true"><thead><tr><th width="249.75">Parameter</th><th>Example</th></tr></thead><tbody><tr><td><strong>Weight</strong> of a single item (in grams)</td><td><pre class="language-json"><code class="lang-json"><strong>{
</strong>  "category": "dimensions",
  "key":"weightPerUnit",
  "value":"&#x3C;the weight of a single item in g",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Height</strong> of a single item (in mm)</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"height",
  "value":"&#x3C;the height of a single item in mm>",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Width</strong> of a single item (in mm)</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"width",
  "value":"&#x3C;the width of a single item in mm>",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Length</strong> of a single item (in mm)</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"length",
  "value":"&#x3C;the length of a single item in mm>",
  "type":"NUMBER"
}
</code></pre></td></tr></tbody></table>

### Category salesPrice

Users can only supply sales prices to the platform via listing attributes. The sales price is particularly relevant for [facilities with a type supplier](https://docs.fulfillmenttools.com/documentation/getting-started/facilities/supplier-facilities). These facilities sell or deliver articles to other facilities. Therefore, it might be necessary to define the price at which these supplier facilities sell their listings to other facilities or facility groups.

In addition, sales prices can also be defined based on tags applied to an order. This allows suppliers to configure different prices depending on the sales channel, customer segment, or any other order‑level context represented by a tag. When an order carries a specific tag, the platform can automatically select and apply the corresponding salesPrice. This enables suppliers to manage channel‑specific or conditional pricing without maintaining multiple separate listings.

{% hint style="info" %}
An example of creating a listing with a sales price is available in the [Sales price with currency](#sales-price-with-currency) example.
{% endhint %}

Attributes with the category `salesPrice`:

* Can only contain the following keys: `valuePerUnit`, `currency`, and `numberOfDecimalPlaces`.
* The `valuePerUnit` key:
  * This key is mandatory.
  * Its `value` defines the fallback `salesPrice` if no `context` is defined, or the `salesPrice` for the respective facility or facility group if a `context` is defined. The value must not contain commas or dots. If the `numberOfDecimalPlaces` key is not defined, the system uses the default value stored for the respective currency. For example, a value of "400" with a `numberOfDecimalPlaces` of "2" would be interpreted as "4.00".
  * Its `priority` describes the hierarchy (from low to high) in which the system applies the configured prices. The priority must be unique for the `valuePerUnit` key across all attributes with the `salesPrice` category per listing.
* The `currency` key:
  * This key is mandatory.
  * It defines the currency the listing is sold in. If there are multiple currencies for different facilities or facility groups, multiple currency attributes with `contexts` must be defined.
  * It must have unique `key` and `context.value` pairs.
* The `numberOfDecimalPlaces` key:
  * This key is optional. If it is not defined, the system uses the default value stored for the respective currency.
  * To apply a different number of decimal places per currency or facility (or facility group), a context must be defined.

{% hint style="warning" %}
It's not possible to configure multiple sales prices for the same facility or facility group.
{% endhint %}

## Special keys

Special keys are predefined keys that have a special function in the platform.

<table><thead><tr><th width="303">Key</th><th>Comment</th></tr></thead><tbody><tr><td><code>%%subtitle%%</code></td><td>Can be used in the context of the <code>descriptive</code> category to show the attribute directly below the line item in fulfillmenttools clients.</td></tr><tr><td><code>BRAND</code></td><td>Can be used to add information about the article's brand. This allows users to filter and search by brand in Backoffice. It's used in the context of the <code>miscellaneous</code> category.</td></tr></tbody></table>

## Article attribute inheritance

Entities inherit article attributes upon their creation within fulfillmenttools. When a user supplies article attributes to order line items, all subsequent entities inherit these attributes. If a user also supplies article attributes to listings, the system uses these as a fallback.

{% hint style="warning" %}
**Limitations**

Each `attributes` object has a character limit of 15,360 characters because the system serializes the entire object as a string. This corresponds to approximately 15 attribute objects with around 1024 characters each. The fulfillmenttools API returns an `HTTP 400` error code if a user attempts to create or update an entity that exceeds this limit.
{% endhint %}

## Examples

### Shop price with currency

In this example, the article attributes for the `shop` price are depicted with a currency. The other price categories, such as `insurance` and `customs`, work similarly. In this example, the article would cost 13.37 EUR.

```json
{
  "quantity": 2,
  "article": {
    "tenantArticleId": "111222333",
    "title": "T-Shirt",
    "imageUrl": "https://loremflickr.com/320/240/shirt",
    "attributes": [
      {
        "key": "valuePerUnit",
        "category": "shop",
        "type": "NUMBER",
        "value": "1337"
      },
      {
        "key": "currency",
        "category": "shop",
        "type": "CURRENCY",
        "value": "EUR"
      }
    ]
  }
}
```

### Subtitles and descriptive attributes

When creating an order, users can add attributes as `ArticleAttributeItems` on the article within the line items. The following example shows a line item with a brand and further product information. In this case, the brand would be shown as the subtitle in the [Operations app](https://docs.fulfillmenttools.com/documentation/apps/operations-app).

```json
{
  "quantity": 2,
  "article": {
    "tenantArticleId": "111222333",
    "title": "T-Shirt",
    "imageUrl": "https://loremflickr.com/320/240/shirt",
    "attributes": [
      {
        "key": "%%subtitle%%",
        "value": "Super Brand",
        "category": "descriptive",
        "priority": 100
      },
      {
        "key": "Color",
        "value": "white",
        "category": "descriptive",
        "priority": 101
      },
      {
        "key": "Size",
        "value": "M",
        "category": "descriptive",
        "priority": 102
      }
    ]
  }
}
```

<figure><img src="https://content.gitbook.com/content/Lrrr5jgTsDuR38gNJIrm/blobs/hW8PvoEKX8OoxVnWLkrq/article-attributes.png" alt="Example of article attributes displayed in a client interface" width="188"><figcaption><p>A client application displaying the subtitle and other descriptive attributes including their keys.</p></figcaption></figure>

### Sales price with currency

In this example, a user creates a listing in a supplier facility along with sales prices and respective currencies. The code sample reflects the values described in the table below:

| Facility or Facility group | Sales price | Priority |
| -------------------------- | ----------- | -------- |
| Fallback                   | 4.00 EUR    | -        |
| Facility GB                | 2.00 GBP    | 700      |
| Facility group CH          | 3.00 CHF    | 500      |

```http
PUT https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings
```

```json
{
  "listings": [
    {
      "tenantArticleId": "4711",
      "title": "Adidas Superstar",
      "attributes": [
        {
          "key": "valuePerUnit",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "400"
        },
        {
          "key": "currency",
          "category": "salesPrice",
          "type": "CURRENCY",
          "value": "EUR"
        },
        {
          "key": "numberOfDecimalPlaces",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "2"
        },
        {
          "key": "valuePerUnit",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "300",
          "priority": 500,
          "context": {
            "type": "FACILITY_GROUP",
            "value": "uuid-facility-group-ch"
          }
        },
        {
          "key": "currency",
          "category": "salesPrice",
          "type": "CURRENCY",
          "value": "CHF",
          "context": {
            "type": "FACILITY_GROUP",
            "value": "uuid-facility-group-ch"
          }
        },
        {
          "key": "numberOfDecimalPlaces",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "2",
          "context": {
            "type": "FACILITY_GROUP",
            "value": "uuid-facility-group-ch"
          }
        },
        {
          "key": "valuePerUnit",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "200",
          "priority": 700,
          "context": {
            "type": "FACILITY",
            "value": "uuid-facility-gb"
          }
        },
        {
          "key": "currency",
          "category": "salesPrice",
          "type": "CURRENCY",
          "value": "GBP",
          "context": {
            "type": "FACILITY",
            "value": "uuid-facility-gb"
          }
        },
        {
          "key": "numberOfDecimalPlaces",
          "category": "salesPrice",
          "type": "NUMBER",
          "value": "2",
          "context": {
            "type": "FACILITY",
            "value": "uuid-facility-gb"
          }
        }
      ]
    }
  ]
}
```