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

Attention: attributes aren't the same as customAttributes.

Example entry of the attributes model:

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

Category	Comment
descriptive	The key and value are shown in fulfillmenttools clients, such as Backoffice. This category can enhance the displayed data to simplify data processing.
pickingSequence	Defines the sequence in which line items are ordered during picking.
miscellaneous (default)	The fulfillmenttools clients don't currently use this category, except for the BRAND key.
customs	Includes keys such as valuePerUnit, hsCode, and currency. Other keys are also possible for this attribute.
insurance	Defines insurance-related data and can include keys such as valuePerUnit and currency.
shop	Defines the customer shop price and can include keys such as valuePerUnit and currency.
dimensions	Defines dimensions and includes keys such as weightPerUnit, height, width, and length. 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.
salesPrice	Defines the price at which supplier facilities sell the listing to other facilities in the network.

For the categories customs, insurance, shop, salesPrice, and dimensions, the type field is mandatory. The type can be CURRENCY (ISO-4217), NUMBER, or STRING. For all other categories, the type field is optional.

Special categories

Category dimensions

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.

Parameter	Example
Weight of a single item	{ "category": "dimensions", "key":"weightPerUnit", "value":"<the weight of a single item>", "type":"NUMBER" }
Height of a single item	{ "category": "dimensions", "key":"height", "value":"<the height of a single item>", "type":"NUMBER" }
Width of a single item	{ "category": "dimensions", "key":"width", "value":"<the width of a single item>", "type":"NUMBER" }
Length of a single item	{ "category": "dimensions", "key":"length", "value":"<the length of a single item>", "type":"NUMBER" }

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

An example of creating a listing with a sales price is available in the Sales price with currency example.

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.

It's not possible to configure multiple sales prices for the same facility or facility group.

Special keys

Special keys are predefined keys that have a special function in fulfillmenttools.

Key	Comment
%%subtitle%%	Can be used in the context of the descriptive category to show the attribute directly below the line item in fulfillmenttools clients.
BRAND	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 miscellaneous category.

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.

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.

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.

Other categories, such as insurance and customs, follow the same structure.

{
...
    "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 as shown below:

Listing code example

{
    "listings": [
        {
            "tenantArticleId": "111222333",
            "title": "Oversized Heavyweight Sweatshirt",
            "imageUrl": "https://loremflickr.com/320/240/sweatshirt",
            "attributes": [
                {
                    "key": "%%subtitle%%",
                    "value": "7718881",
                    "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"
                }
            ]
        }
    ]
}     

Order code example

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

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

{
  "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"
          }
        }
      ]
    }
  ]
}