Listing

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

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.

Listings & Stocks

While a listing holds master data for a product within a facility such as title, barcode, or price, a stock refers to one or more items in a facility with the same attributes. Stocks can exist without listings and the other way around. However, we advise to always create listings for stocks so that the various stocks are assigned to the corresponding product and product information can be displayed in the clients. Go here for more information on stocks.

Mandatory Fields

• 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 Fields

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-4217 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
            }
        }
    }

Stock Available Until

The availableUntil field defines until when a stock is included in the stock availability which is, e.g., used to communicate available stock to shop systems. For customer orders, the availability check ensures that stock has not exceeded its availableUntil value until is is delivered to the customer.

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. For more information please refer to Availability.

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

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>",
    "stockAvailableUntil": {
        "calculationBase": "EXPIRY",
        "modifier": "-P30D"
      }
  }

• StockAvailableUntil defaults to the expiry date, i.e., if there is no stockAvailableUntil configured on the listing, the stockAvailableUntil of a stock will be its expiry date.

• An undefined stockAvailableUntil on stocks (e.g. no stockAvailableUntil and no expiry is configured) means, the stock will be available for an unlimited period of time.

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 not considered for incoming orders.

API documentation

For multiple listings

Get a facility with the given ID

get

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to get listing

Query parameters

startAfterIdstringoptional

all entities after given Id

sizeinteger · default: 25optional

number of facilities to show

tenantArticleIdsstring[] · max: 500optional

Array of tenantArticleIds

scannableCodestringoptional

limit results to this scannableCode

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings'

200

401

403

404

200

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

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

Create or Update listings of a facility with the given ID

put

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to get its listing

Body

listingsall of[] · min: 1 · max: 500required

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings' \
  --header 'Content-Type: application/json' \
  --data '{
    "listings": [
      {
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ],
        "imageUrl": "text",
        "price": 1200,
        "stockinformation": {
          "reserved": 24,
          "stock": 42
        },
        "tenantArticleId": "4711",
        "title": "Adidas Superstar",
        "partialStocks": [
          {
            "tenantPartialStockId": "text",
            "stockinformation": {
              "reserved": 24,
              "stock": 42
            },
            "scores": [
              {
                "scoreType": "RATING",
                "scoreName": "ZONE",
                "scoreValue": 1
              }
            ],
            "location": {
              "locationRef": "text",
              "scannableCodes": [
                "text"
              ]
            }
          }
        ],
        "weight": 1,
        "scanningRule": {
          "values": []
        },
        "scannableCodes": [
          "text"
        ],
        "outOfStockBehaviour": "BACKORDER",
        "availabilityTimeframe": {
          "start": "2020-02-03T08:45:50.525Z"
        },
        "tags": [],
        "measurementUnitKey": "liter",
        "stockProperties": {
          "ANY_ADDITIONAL_PROPERTY": {
            "inputType": "DATE",
            "required": true,
            "defaultValue": "text"
          }
        },
        "legal": {
          "hsCode": "text"
        }
      }
    ]
  }'

200

401

403

404

200

No body

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

deletes all listings of a facility with the given ID

delete

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to delete all listings of

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings'

200

401

403

404

200

No body

Facility listings were found and successfully deleted

For a specific listing

Get a Listings with the given ID

get

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to get listing

tenantArticleIdstringrequired

tenantArticleId of listing you want to get

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}'

200

401

403

404

200

{
  "attributes": [
    {
      "category": "descriptive",
      "key": "%%subtitle%%",
      "priority": 100,
      "value": "585er Gold"
    }
  ],
  "imageUrl": "text",
  "price": 1200,
  "stockinformation": {
    "reserved": 24,
    "stock": 42,
    "available": 24
  },
  "tenantArticleId": "4711",
  "title": "Adidas Superstar",
  "partialStocks": [
    {
      "tenantPartialStockId": "text",
      "stockinformation": {
        "reserved": 24,
        "stock": 42
      },
      "scores": [
        {
          "scoreType": "RATING",
          "scoreName": "ZONE",
          "scoreValue": 1
        }
      ],
      "location": {
        "locationRef": "text",
        "scannableCodes": [
          "text"
        ]
      }
    }
  ],
  "weight": 1,
  "scanningRule": {
    "values": []
  },
  "scannableCodes": [
    "text"
  ],
  "outOfStockBehaviour": "BACKORDER",
  "availabilityTimeframe": {
    "start": "2020-02-03T08:45:50.525Z"
  },
  "tags": [],
  "measurementUnitKey": "liter",
  "stockProperties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "inputType": "DATE",
      "required": true,
      "defaultValue": "text"
    }
  },
  "legal": {
    "hsCode": "text"
  },
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "facilityId": "4711",
  "id": "fsfdsf87fsd",
  "status": "ACTIVE"
}

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

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

delete

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to delete a listing of

tenantArticleIdstringrequired

tenant ID of the articles listing you want to delete

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}'

200

401

403

404

200

No body

Facility listing was found and successfully deleted

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

patch

Authorizations

Path parameters

facilityIdstringrequired

ID of facility you want to patch a listing of

tenantArticleIdstringrequired

tenant ID of the articles listing you want to patch

Body

actionsall of[] · min: 1required

versioninteger · int64required

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

Example: 42

Responses

application/json

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://%%HOST%%//api/facilities/{facilityId}/listings/{tenantArticleId}' \
  --header 'Content-Type: application/json' \
  --data '{
    "actions": [
      {
        "action": "ModifyListing",
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ],
        "imageUrl": "text",
        "price": 1200,
        "status": "ACTIVE",
        "stockinformation": {
          "reserved": 24,
          "stock": 42
        },
        "subtitle": "44 2/3",
        "title": "Adidas Superstar",
        "tags": [],
        "scanningRule": {
          "values": []
        },
        "scannableCodes": [
          "text"
        ],
        "weight": 1,
        "outOfStockBehaviour": "BACKORDER",
        "availabilityTimeframe": {
          "start": "2020-02-03T08:45:50.525Z"
        },
        "measurementUnitKey": "kg",
        "stockProperties": {
          "ANY_ADDITIONAL_PROPERTY": {
            "inputType": "DATE",
            "required": true,
            "defaultValue": "text"
          }
        },
        "legal": {
          "hsCode": "text"
        }
      }
    ],
    "version": 42
  }'

200

400

401

403

404

409

200

[
  {
    "attributes": [
      {
        "category": "descriptive",
        "key": "%%subtitle%%",
        "priority": 100,
        "value": "585er Gold"
      }
    ],
    "imageUrl": "text",
    "price": 1200,
    "stockinformation": {
      "reserved": 24,
      "stock": 42,
      "available": 24
    },
    "tenantArticleId": "4711",
    "title": "Adidas Superstar",
    "partialStocks": [
      {
        "tenantPartialStockId": "text",
        "stockinformation": {
          "reserved": 24,
          "stock": 42
        },
        "scores": [
          {
            "scoreType": "RATING",
            "scoreName": "ZONE",
            "scoreValue": 1
          }
        ],
        "location": {
          "locationRef": "text",
          "scannableCodes": [
            "text"
          ]
        }
      }
    ],
    "weight": 1,
    "scanningRule": {
      "values": []
    },
    "scannableCodes": [
      "text"
    ],
    "outOfStockBehaviour": "BACKORDER",
    "availabilityTimeframe": {
      "start": "2020-02-03T08:45:50.525Z"
    },
    "tags": [],
    "measurementUnitKey": "liter",
    "stockProperties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "inputType": "DATE",
        "required": true,
        "defaultValue": "text"
      }
    },
    "legal": {
      "hsCode": "text"
    },
    "created": "2020-02-03T08:45:51.525Z",
    "lastModified": "2020-02-03T09:45:51.525Z",
    "version": 42,
    "facilityId": "4711",
    "id": "fsfdsf87fsd",
    "status": "ACTIVE"
  }
]

Facility listing was found and successfully patched