Measurement Units

Define what each element of a stock represents.

In the fulfillmenttools platform each product (identified by one tenantArticleId in a facility) is tracked in one unit. The meaning of a unit is completely arbitrary but will commonly represent a physical unit like "g" or "kg" or for countable goods something like "pieces" or "pcs". Since each product is kept in just one measurement unit, operations like adding or moving stock do not need to validate or convert units between stocks.

Defining measurement unit keys for a listing

Units can be defined in the measurementUnitKey in the Iisting. The key that is defined will be displayed in our clients, e.g., during picking if no measurementUnit is defined for the key. It is not required to define units for products. When no unit is set in the listing, no validation will take place and our clients will default to a localized version of "pieces".

Both a missing "measurementUnitKey" field and "measurementUnitKey: null" are treated as no unit.

If you want to track one product in different units (for example as bulk by weight and also by prepackaged quantity) please create two Listings with different tenantArticleIds: "xyz-123-bulk" and "xyz-123-packaged". Any such setup should reflect the reality of the goods handling in your warehouse / facility.

Create or Update listings of a facility with the given ID

PUThttps://%%HOST%%//api/facilities/{facilityId}/listings

Authorization

Path parameters

facilityId*string

ID of facility you want to get its listing

Body

listings for put

listings*array of ListingForReplacement (object)

Response

Facility listing was found & you were allowed to access it.

Request

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "listings": [
        {}
      ]
    }),
});
const data = await response.json();

Update a listing with the given ID of a facility with the given ID

PATCHhttps://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}

Authorization

Path parameters

facilityId*string

ID of facility you want to patch a listing of

tenantArticleId*string

tenant ID of the articles listing you want to patch

Body

listings for put

actions*array of ModifyListingAction (all of)

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Response

Facility listing was found and successfully patched

Body

attributesarray of ListingAttributeItem (all of)

imageUrlstring

A web link to a picture of this article. Please make sure that no authentication is required to fetch the image!

pricenumber

tenantArticleId*string

This is a reference to an article Id

title*string

a title describing the article

weightnumber

scanningRuleScanningRuleConfiguration (object)

Configuration to show the client how the items should be scanned during picking

scannableCodesarray of string

outOfStockBehaviourenum

BACKORDER

availabilityTimeframeAvailabilityTimeframe (object)

tagsarray of TagReference (object)

measurementUnitKeystring

Identifier for items unit of measurement.

stockPropertiesobject

legalListingLegal (object)

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

stockinformationStockInformation (object)

facilityId*string

This is a reference to a facility

id*string

status*enum

ACTIVEINACTIVE

scannableCodesarray of string

Request

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "version": 42,
      "actions": [
        {
          "action": "ModifyListing"
        }
      ]
    }),
});
const data = await response.json();

Response

[
  {
    "attributes": [
      {
        "category": "descriptive",
        "key": "%%subtitle%%",
        "priority": 100,
        "value": "585er Gold"
      }
    ],
    "imageUrl": "text",
    "price": 1200,
    "tenantArticleId": "4711",
    "title": "Adidas Superstar",
    "weight": 0,
    "scanningRule": {
      "values": [
        {
          "priority": 0,
          "scanningRuleType": "ARTICLE"
        }
      ]
    },
    "scannableCodes": [
      "text"
    ],
    "outOfStockBehaviour": "BACKORDER",
    "availabilityTimeframe": {
      "start": "2020-02-03T08:45:50.525Z"
    },
    "tags": [
      {
        "value": "text",
        "id": "text"
      }
    ],
    "measurementUnitKey": "liter",
    "legal": {
      "hsCode": "text"
    },
    "created": "2020-02-03T08:45:51.525Z",
    "lastModified": "2020-02-03T09:45:51.525Z",
    "version": 42,
    "stockinformation": {
      "stock": 42,
      "reserved": 24,
      "available": 24
    },
    "facilityId": "4711",
    "id": "fsfdsf87fsd",
    "status": "ACTIVE"
  }
]

curl --location --request PUT 'https://<apiHostname>/api/facilities/8f5bd918-ad32-4800-9818-54d3f4209b03/listings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authToken>' \
--data '{
    "listings": [
        {
            "tenantArticleId": "flour",
            "price": 0.8,
            "version": 1,
            "title": "Sacks of flour",
            "scannableCodes": [],
            "attributes": [],
            "measurementUnitKey": "stone"
        }
    ]
}
'

Defining translations for measurement units

To localize the long-name and abbreviation of a unit for the client applications you can create MeasurementUnit entities corresponding to the listing.measurementUnitKey. If no MeasurementUnit is defined for a key, the key will be displayed in the apps.

Create measurementUnit

POSThttps://%%HOST%%//api/measurementunits

Authorization

Body

abbreviationLocalized*all of

Abbreviation of the unit. Maximum 4 chars long.

key*string

Descriptor for the measurement unit

nameLocalized*LocaleString (object)

requiresMeasurementboolean

Indicates that the given unit need to be measured.

Response

Successfully created the measurementUnit.

Body

abbreviationLocalized*all of

Abbreviation of the unit. Maximum 4 chars long.

key*string

Descriptor for the measurement unit

nameLocalized*LocaleString (object)

requiresMeasurementboolean

Indicates that the given unit need to be measured.

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Request

const response = await fetch('https://%%HOST%%//api/measurementunits', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "abbreviationLocalized": {
        "de_DE": "kg",
        "en_US": "kg",
        "ru_RU": "кг"
      },
      "key": "kilogramm"
    }),
});
const data = await response.json();

Response

{
  "abbreviation": "kg",
  "id": "c5300790-9477-475c-bd6d-98e5d61f6413",
  "name": "kilogramm"
}

curl --location 'https://<apiHostname>/api/measurementunits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authToken>' \
--data '{
    "key": "stone",
    "nameLocalized": { "de_DE": "Stone", "en_US": "Stone" },
    "abbreviationLocalized": { "de_DE": "st", "en_US": "st" },
    "requiresMeasurement": false
}'

Unit validation in inbound processes

If you are using our system for goods receipts, we highly recommend defining units for each product in the respective listing of this product's facility.

Since no conversion between units take place automatically it is important to specify the correct unit when new goods are accepted into the system. This eliminates a common source of critical errors in stock levels.

When a measurementUnitKey is set on the corresponding listing each new line item in inboundProcess.purchaseOrder.requestedItems and inboundProcess.receipts.receivedItems is validated against it: All quantities MUST match the unit of the Listing.

Attention: When creating an InboundProcess with a PurchaseOrder with unit "xyz" and changing the listing.measurementUnitKey to something else ("qwe") the inboundProcess.purchaseOrder must now be patched/replaced to reflect the correct unit again before a receipt can created in the inventory app. This is intentional and ensures the consistency of new stock levels in the facility. In general it is not advised to change the unit of a product in a facility without careful consideration, but in some cases it might be desired to start with no unit on the listing (= no validation) and transition to stricter rules later.

PreviousInventory Traits NextStorage Location Recommendations

Last updated 1 month ago

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}', { method: 'PATCH', headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "version": 42, "actions": [ { "action": "ModifyListing" } ] }), }); const data = await response.json();

[ { "attributes": [ { "category": "descriptive", "key": "%%subtitle%%", "priority": 100, "value": "585er Gold" } ], "imageUrl": "text", "price": 1200, "tenantArticleId": "4711", "title": "Adidas Superstar", "weight": 0, "scanningRule": { "values": [ { "priority": 0, "scanningRuleType": "ARTICLE" } ] }, "scannableCodes": [ "text" ], "outOfStockBehaviour": "BACKORDER", "availabilityTimeframe": { "start": "2020-02-03T08:45:50.525Z" }, "tags": [ { "value": "text", "id": "text" } ], "measurementUnitKey": "liter", "legal": { "hsCode": "text" }, "created": "2020-02-03T08:45:51.525Z", "lastModified": "2020-02-03T09:45:51.525Z", "version": 42, "stockinformation": { "stock": 42, "reserved": 24, "available": 24 }, "facilityId": "4711", "id": "fsfdsf87fsd", "status": "ACTIVE" } ]