Listings
Now that our facilities are added into the fulfillmenttools platform, we need to add master data (listings) for that facilities.
What are listings?
Listings are the items we offer in a facilty. Even though they are optional, they are very helpful for several functionalities, especially the dynamic order routing. For more information on the entity, please see .
Why has every facility its own listings?
An article that we offer in Lisbon might not run at all in Helsinki. That's why it makes more sense to not list that article in facilities which do not sell an item. In this tutorial the items offered are very similar. In Helsinki, LU.XY does not sell summer dresses and sandals. In Lissabon, they don't sell winter boots and parkas.
Adding listings to the facilities
After we decided which items to list in which facility, we can start to add them to the facilities. In this tutorial page, we start with the store in Frankfurt, where all items are sold. You need the ID of the facility you want to create a listing in. The ID can be received via the facility endpoint, which we used to create the facility.
For adding a listing, we send a PUT request to the listings endpoint containing a ListingsForCreation object:
The response should be an empty 200 OK response, if the request was successful. Let's have a look at the properties:
tenantArticleId: The ID the article has in your systems, must be unique.
price: The price at which the article is sold.
title: The title that article has.
imageUrl: URL where an image is found of that article, will be shown in the clients we offer.
scannableCodes: List of scannable codes for that item. Used while picking. Might be the EAN or any other barcode.
mesaurementUnitKey: Unit in which that article is count, in this case we sell hole units of garments. In the food context, that might a weighing unit like kilograms.
With the facilities and the listings being set, we can start using the orders endpoint for testing.
After you created your first facility, you can (but don't have to) add some listings (articles) for this facility.
Placeholders
| Placeholder | Replace with | Example |
|---|---|---|
| JWT from Identity provider |
|
| the ID of the facility the listing is for |
|
Creating a listing with stock properties
Stock Properties allow tracking of specific values on stock. The listing defines which properties should be tracked for stocks that belong to this specific listing. Moreover, its is configurable in the listing, whether it is mandatory to track stock properties, e.g., during goods receipt and if the value is expected to be a text or date.
Creating a listing with stockAvailableUntil
In the listing it can be specified until when the corresponding stock should be available. The availableUntil value is set upon stock creation if configured in listing.
calculation base:Set field to EXPIRY, if stock should become unavailable before it expires. EXPIRY needs to be configured in the stockProperties before it can be used here. Set field to CREATION if stock should become unavailable some time after it was created.modifier:Time span which is applied to the calculation base to calculate time point when stock should become unavailable. Use negative values to move the date backwards. Example: "-P30D" places the "availableUntil" value 30 days before the calculated date.
Create a listing with measurement unit
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.
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.
Integration layer
We highly recommend using events on the integration layer to handle the stock topic. For example an event from the POS cashier could trigger a stock change in the fulfillmenttools platform. Furthermore, we provide an event if there is a stock change. More information can be read here.
Last updated