Listing

Summary

A listing is an item or a commodity that is sold in a given facility. It holds information on the product such as price, barcodes or attributes. A listing does not represent the actual stock, i.e. the (available) quantity of a product in a facility. All information specific to individual pieces of a product is kept in stocks.

Table of Contents

1. Description

2. Mandatory Values

3. Optional Values

   1. Attributes

   2. Price

   3. Currency

   4. Weight

   5. Scanning Rule

   6. Scannable Codes

   7. Out of stock behaviour

   8. Availability Timeframe

   9. Tags

   10. Measurement Unit Key

   11. Stock Properties

   12. Legal

   13. Custom Attributes

   14. Status

4. API documentation

Description

There are various values that can be defined for a listing that are used for descriptive purposes and/or that have an influence on processes.

Mandatory Values

• tenantArticleId: identifier for the product in the respective facility

• title: name of the product that is also displayed in clients (e.g. in our app)

Optional Values

Attributes

Attributes can be used to store listing specific information such as product category or description. Moreover, they can be used to customize processes related to listings such as the picking sequence. For more information please refer to customization via attributes.

Price

The price at which the item is sold in this facility.

Currency

A listing can only have a specified price in a single currency. There can only exist one listing for the same tenantArticleId in the same facility and thus, only one currency per facility per tenantArticleId. Any currency that is part of the ISO 4217O standard can be configured.

Weight

Weight of the product that is used to calculate the shipping weight for an order.

Scanning Rule

Configuration to show the client how the items should be scanned during picking. For more information please refer to scanning configuration.

Scannable Codes

A list of barcodes that allows identifying items via barcode scan.

Out of Stock Behaviour

Defines behaviour if customer places an order for a product that is currently out of stock or unavailable for immediate shipment. For more information please refer to How to make a listing Pre-/Backorderable.

Availability Timeframe

If a listing is already flagged with outOfStockBehaviour = "BACKORDER" and has anavailabilityTimeFrameconfigured, then orders containing that listing are accepted but only assigned a specific facility when the date defined in the availabilityTimeFrame is reached.

Tags

Tags consist of a Tag-Reference plus allowed values for each Tag. They can be used to map very individual processes and to customize entities according to special needs. For more information please refer to Tags and Stickers Concept.

Measurement Unit Key

The unit in which the product is counted or measured. By default, the counting unit is pieces. However, other units like gram or custom units can be defined. For more information please refer to Measurement Units.

Stock Properties

Stock Properties allow tracking of specific values on a set of items, a Stock. A common example for properties are expiry date or batch number. 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. For more information please refer to Stock Properties.

curl -sSL -X PUT 'https://your.api.fulfillmenttools.com/api/facilities/{facilitiyId}/listings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "tenantArticleId": "<your product ID>",
    "title": "<the listing title>",
    "stockProperties": {
        "<your property key>": {
            "inputType": "DATE",
            "required": true
            }
        }
    }

Legal

Under legal, users can specify a hsCode. "HS" stands for "Harmonized system" and is a description and coding system used by authorities to classify a product. In our platform, it is used, e.g., when requesting a carrier label for sending a package.

Custom Attributes

Custom Attributes can be used to carry information that might be of interest to connectors or services outside of fulfillmenttools. However, they do not have any influence on the behaviour of the fulfillmenttools platform. For more information please refer to Custom Attributes.

Status

Listings can be active or inactive. Deactivated listings are assumed to currently not be sold, but at some point later in time they will be (e.g. seasonal products).

Deactivated listings are still considered for incoming orders.

API documentation

For multiple listings

Get a facility with the given ID

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

Authorization

firebase

Path parameters

facilityId*string

ID of facility you want to get listing

Query parameters

Response

200401403404

Facility was found & you were allowed to access it. The result is in the body.

Body

application/json

listingsarray of StrippedListing (all of)

totalinteger

Total number of found entities for this query

Request

JavaScriptCurl

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "listings": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "version": 42,
      "id": "fsfdsf87fsd",
      "status": "ACTIVE",
      "tenantArticleId": "4711"
    }
  ],
  "total": 42
}

Create or Update listings of a facility with the given ID

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

Authorization

firebase

Path parameters

facilityId*string

ID of facility you want to get its listing

Body

application/json

listings for put

listings*array of ListingForReplacement (object)

Response

200401403404

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

Request

JavaScriptCurl

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();

deletes all listings of a facility with the given ID

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

Authorization

firebase

Path parameters

facilityId*string

ID of facility you want to delete all listings of

Response

200401403404

Facility listings were found and successfully deleted

Request

JavaScriptCurl

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

For a specific listing

Get a Listings with the given ID

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

Authorization

firebase

Path parameters

facilityId*string

ID of facility you want to get listing

tenantArticleId*string

tenantArticleId of listing you want to get

Response

200401403404

Listing is found & you were allowed to access it. The result is in the body.

Body

application/json

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

JavaScriptCurl

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}', {
    method: 'GET',
    headers: {},
});
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"
}

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

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

Authorization

firebase

Path parameters

facilityId*string

ID of facility you want to delete a listing of

tenantArticleId*string

tenant ID of the articles listing you want to delete

Response

200401403404

Facility listing was found and successfully deleted

Request

JavaScriptCurl

const response = await fetch('https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}', {
    method: 'DELETE',
    headers: {},
});
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

firebase

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

application/json

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

200400401403404409

Facility listing was found and successfully patched

Body

application/json

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

JavaScriptCurl

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