Core concepts & terminology

This page aims to give you an overview of the core concepts you will see when working with our platform and this documentation.

Order

We see an order as something that comes from your shop system and needs to be fulfilled in one of your locations. An order contains information on the customer, their delivery preferences, the items which are ordered and optional some additional information.

{
  "consumer": {
    "addresses": [
      {
        "firstName": "Michael",
        "lastName": "Miller",
        "street": "Schillerweg",
        "houseNumber": "12B",
        "postalCode": "40213",
        "city": "Düsseldorf",
        "country": "DE"
      }
    ],
    "email": "[e-mail]"
  },
  "deliveryPreferences": {
    "shipping": {
      "serviceLevel": "DELIVERY"
    }
  },
  "orderDate": "2023-10-23T08:45:50.525Z",
  "tenantOrderId": "de-cgn-584163fAWR",
  "orderLineItems": [
    {
      "article": {
        "tenantArticleId": "8504",
        "title": "Oranges - 5 kg net"
      },
      "quantity": 5
    },
    {
      "article": {
        "tenantArticleId": "9761",
        "title": "Gaffel Kölsch - 24x0.33l"
      },
      "quantity": 1
    }
  ]
}

Facility

A facility is one of your locations where you fulfill orders. This might be your warehouse or one of your stores. This one of the core entities of our platform.

{
  "name": "dreams agency cologne 1",
  "address": {
    "companyName": "dreams fulfilling GmbH",
    "street": "Butzweilerstraße",
    "houseNumber": "35-39",
    "postalCode": "50829",
    "city": "Köln",
    "country": "DE"
  },
  "locationType": "STORE",
  "status": "ONLINE",
  "services": [{ "type": "SHIP_FROM_STORE" }]
}

Routing

One of the things making our platform unique is our dynamic routing which finds the best option to fulfill an order at the current time. We distinguish between fences - these are criteria that have to be fulfilled and so-called ratings, dynamic criteria. A fence might be that the facility has to be in the same country as the customer. A rating could be the geodistance between the facility and the customer. Also, the order could optionally be split and fulfilled in more than one facility.

Listing

When placing orders as mentioned above, you can give additional information such as the size, the color or other data about an article item. When having a fixed set of articles you provide in a facility, you might those information to be mapped automatically. To offer this functionality, you can add listings. Listings are created for an existing facility and typically represent an type of item which is sold in that facility. It contains all relevant attributes, which are the same for each unit. It does not contain item-specific information and/or information about the current stock levels.

{
  "title": "Slim fit chino pants",
  "tenantArticleId": "1752930",
  "imageUrl": "https://images.your-shop.com/chino.jpg",
  "price": 79.95,
  "attributes": [
    {
      "category": "descriptive",
      "key": "color",
      "value": "beige"
    },
    {
      "category": "descriptive",
      "key": "waist",
      "value": "29"
    },
    {
      "category": "descriptive",
      "key": "length",
      "value": "30"
    }
  ],
  "scannableCodes": ["4012345678901", "1752930", "CHINO-175-29-30"]
}

Stock

All sellable items in the facility are represented as stock, and stocks most importantly contain information on how many items are present. Stock is typically linked to a listing (which describes the attributes of the items). Most of the attributes will be described via the listing. However, there might be stock-specific information, which differs from item to item, like best-before-dates.

{
    "tenantArticleId": "1752930",
    "facilityRef": "0dee02e8-f6a7-4080-b5ab-ffa477132f35",
    "value": 83
}