Placing orders

More Orders-API information can be found here: REST API documentation - Orders

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 scannable codes that need to be scanned when the item is picked in the facility. Furthermore, we recommend configuring the delivery preferences for that order.

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:

POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/orders

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

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, some properties in the JSON 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 its 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 on the platform.

• lastModified: Time the order was most recently modified.

What to do after successfully placing the first order?

After you successfully tested placing some orders, we highly recommend using a piece of software that 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.