Placing orders

With facilities to fulfill orders from and listings created in those facilities, we can start using the orders endpoints.

What is an order?

An order inside the fulfillmenttools platform is the usual entry point when starting the fulfillment process with our platform. We consume this information from an order object:

• customer's location

• time the order was placed

• line items of the order

  • article

    • title of that article

    • article ID in your system

  • quantity

However, this is the minimum information the platform needs for order fulfillment, there can be more information. For example an order line item can contain a list of scannble codes which need to be scanned when the item is picked in the facility. Furthermore we recommend configuring the delivery preferences for that order. A detailed overview of the information that can be stored in an order, please see the API reference for orders.

Placing the order

To place an order we need the information mentioned above, we need to make a POST call to the orders endpoint. This call might look like this:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/orders'

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/orders' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "consumer": {
    "addresses": [
      {
        "salutation": "Meneer",
        "firstName": "David",
        "lastName": "van den Boomgaard",
        "street": "Rombout Hogerbeetsstraat",
        "houseNumber": "96",
        "postalCode": "1052 XM",
        "province": "Noord-Holland",
        "city": "Amsterdam",
        "country": "NL"
      }
    ],
    "email": "[e-mail]"
  },
  "orderDate": "2024-01-18T08:45:50.525Z",
  "orderLineItems": [
    {
      "article": {
        "tenantArticleId": "TSHIRT-W-2468",
        "title": "Basic T-Shirt White"
      },
      "quantity": 10
    },
    {
      "article": {
        "tenantArticleId": "JEANS-B-2605",
        "title": "Washed Slim Fit Jeans"
      },
      "quantity": 3
    },
    {
      "article": {
        "tenantArticleId": "SNEAK-W-4891",
        "title": "White Sneakers"
      },
      "quantity": 1
    }
  ],
 "deliveryPreferences": {
    "shipping": {
        "serviceLevel": "DELIVERY"
    }
}
  "tenantOrderId": "R456728546"
}'

You might have noticed, that compared to the listing we have much less information on the articles provided with the call. If there is an active listing for the article ID provided, this will automatically be mapped and therefore we don't need to provide every detail again as we already did when creating the listings.

Calling the mentioned endpoint will result in a 201 CREATED response containing the order object and some additional information:

201 CREATED response

{
    "consumer": {
        "addresses": [
            {
                "salutation": "Meneer",
                "firstName": "David",
                "lastName": "van den Boomgaard",
                "street": "Rombout Hogerbeetsstraat",
                "houseNumber": "96",
                "postalCode": "1052 XM",
                "province": "Noord-Holland",
                "city": "Amsterdam",
                "country": "NL"
            }
        ],
        "email": "[e-mail]"
    },
    "orderDate": "2024-01-18T08:45:50.525Z",
    "orderLineItems": [
        {
            "article": {
                "tenantArticleId": "TSHIRT-W-2468",
                "title": "Basic T-Shirt White"
            },
            "quantity": 10,
            "id": "470006cd-f24c-49c7-bbed-c5be8e53beab"
        },
        {
            "article": {
                "tenantArticleId": "JEANS-B-2605",
                "title": "Washed Slim Fit Jeans"
            },
            "quantity": 3,
            "id": "de126823-588f-4301-b3bf-8f88b5f7a0de"
        },
        {
            "article": {
                "tenantArticleId": "SNEAK-W-4891",
                "title": "White Sneakers"
            },
            "quantity": 1,
            "id": "c84e2998-21ce-49eb-b82a-1a67f18405b5"
        }
    ],
    "status": "OPEN",
    "tenantOrderId": "R456728546",
    "deliveryPreferences": {
        "shipping": {
            "serviceLevel": "DELIVERY"
        }
    },
    "id": "ccc34764-bd3d-415e-b075-d3a7f569f912",
    "tags": [],
    "processId": "cb395eb4-6364-4e06-bb03-20ba47c2dd5a",
    "created": "2024-01-18T13:41:48.081Z",
    "lastModified": "2024-01-18T13:41:48.081Z",
    "version": 1
}

As you can see here, there are some properties in the JSON which are new compared to what we sent to the API. Let's have a look at them.

• id: Every order has an ID to identify.

• version: Version of the order as part of our optimistic locking mechanism.

• orderLineItem.id: Each order line item has it's own ID.

• status: Every order has a status. Freshly posted orders always have the status OPEN.

• tags: Tags are their own entity, which can be helpful when configuring the DOMS ruleset. We'll share more information on that later in the tutorial as this is an empty array anyway.

• processId: A process is an entity containing every entity involved in the whole fulfilling processes. It's ID is stored inside that.

• created: Time the order was created in the platform at.

• lastModified: Time the order was most recent modified.

What to do after successfully placed the first order?

After you successfully tested placing some orders, we highly recommend using a piece of software which receives incoming orders from your shop systems, transforms the information into an OrderForCreation object and posts that into the fulfillmenttools platform. However a fully handwritten software project is imaginable here, we do provide an SDK for TypeScript and have a commercetools certified connector in the commercetools marketplace. Also using LowCode platforms like n8n or an integration platform like Patchworks is a possibility. To assist you with the integration of you marketplace and the further integration, we offer a Client SDKs and a commercetools Connect.