# Article attributes

fulfillmenttools uses article `attributes` to customize processes and enhance the display of information in client applications (Backoffice, Store Operations app, and so on).

{% hint style="warning" %}
**Attention:** `attributes` aren't the same as [`customAttributes`](/documentation/getting-started/custom-attributes.md).
{% 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

{% hint style="warning" %}
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.
{% endhint %}

<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</td><td><pre class="language-json"><code class="lang-json"><strong>{
</strong>  "category": "dimensions",
  "key":"weightPerUnit",
  "value":"&#x3C;the weight of a single item>",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Height</strong> of a single item</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"height",
  "value":"&#x3C;the height of a single item>",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Width</strong> of a single item</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"width",
  "value":"&#x3C;the width of a single item>",
  "type":"NUMBER"
}
</code></pre></td></tr><tr><td><strong>Length</strong> of a single item</td><td><pre class="language-json"><code class="lang-json">{
  "category": "dimensions",
  "key":"length",
  "value":"&#x3C;the length of a single item>",
  "type":"NUMBER"
}
</code></pre></td></tr></tbody></table>

### Category sales price

Users can only supply sales prices to fulfillmenttools via listing attributes. The sales price is particularly relevant for [facilities with a type supplier](/documentation/getting-started/facilities/supplier-facilities.md). 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, fulfillmenttools 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, fulfillmenttools 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 fulfillmenttools.

<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, fulfillmenttools uses these as a fallback.

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

Each `attributes` object has a character limit of 15,360 characters because fulfillmenttools 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

The shop price defines the customer-facing price of an article. The attributes array accepts `valuePerUnit` and `currency` keys within the shop category. If no number of decimal places is defined, the default is 2.\
In the example below, the article costs 13.37 EUR.

{% hint style="info" %}
Other categories, such as `insurance` and `customs`, follow the same structure.
{% endhint %}

```json
{
...
    "orderLineItems": [
        {
            "quantity": 2,
            "tenantArticleId": "111112233",
            "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 a listing or an order, users can add attributes on the article.

The following example shows attributes being added to a listing on creation, and the second tab shows a line item with a subtitle and further product information. The `%%subtitle%%` will always show in the first position.

In this case, the item code would be shown as the subtitle in the [Store Operations app](/documentation/apps/store-operations-app-beta.md) as shown below:

{% tabs %}
{% tab title="Listing code example" %}

<pre class="language-json"><code class="lang-json">{
    "listings": [
        {
            "tenantArticleId": "111222333",
            "title": "Oversized Heavyweight Sweatshirt",
            "imageUrl": "https://loremflickr.com/320/240/sweatshirt",
            "attributes": [
                {
                    "key": "%%subtitle%%",
<strong>                    "value": "7718881",
</strong>                    "category": "descriptive"
                },
                {
                    "key": "Color",
                    "value": "White melange",
                    "category": "descriptive"
                },
                {
                    "key": "valuePerUnit",
                    "category": "shop",
                    "type": "NUMBER",
                    "value": "12000"
                },
                {
                    "key": "currency",
                    "category": "shop",
                    "type": "CURRENCY",
                    "value": "EUR"
                },
                {
                    "key": "Size",
                    "value": "Medium",
                    "category": "descriptive"
                }
            ]
        }
    ]
}     
</code></pre>

{% endtab %}

{% tab title="Order code example" %}

```json
{
...
    "orderLineItems": [
        {
            "quantity": 2,
            "article": {
                "tenantArticleId": "111222333",
                "title": "Oversized Heavyweight Sweatshirt",
                "attributes": [
                    {
                        "key": "%%subtitle%%",
                        "value": "7718881",
                        "category": "descriptive"
                    },
                    {
                        "key": "Color",
                        "value": "White melange",
                        "category": "descriptive"
                    },
                    {
                        "key": "Size",
                        "value": "Medium",
                        "category": "descriptive"
                    }
                ]
            }
        }    
    ],
...
}
```

{% endtab %}
{% endtabs %}

<div><figure><img src="/files/K0HJjiwcz9iZr0hVz2G3" alt="Example of article attributes displayed in a client interface" width="375"><figcaption></figcaption></figure> <figure><img src="/files/jR3nXIOH0xE6oKYkZ1eq" alt="" width="375"><figcaption></figcaption></figure></div>

### 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"
          }
        }
      ]
    }
  ]
}
```


---

# Agent Instructions: 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/articles/article-attributes.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.