Orders

Learn how to place your first order via API.

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.

Example for placing an order

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:

Example for 201 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.

After you successfully added a listing and your first facility, it is time to learn how to place an order which you the pickers in the facility can fulfill.

Placeholders

Placeholder	Replace with	Example
{TOKEN}	JWT from Identity provider	eyJhbGciOX49.eyJzdWV9.dyt0CoI

Restrictions

It is only possible to place an order with a duplicated tenantOrderId if the previous orders are not in the status OPEN, LOCKED, or PROMISED. Otherwise, your order creation request will be denied.

If you want to reuse a tenantOrderId and the previous order is in the status OPEN, LOCKED, or PROMISED, you must cancel the previous order first.

Order Events

ORDER_CREATED

If you have subscribed to ORDER_CREATED webhook events as described in the Eventing tutorial, your service will be notified when a new order has been created. You can evaluate the information from this event, e.g. to start other business processes.

The OrderCreatedWebHookEvent has all the details about the order:

{
  "event": "ORDER_CREATED",
  "eventId": "4395488122884786",
  "payload": {
    "id": "287ce844-fb3d-43f1-bc52-d667db8cbbb5",
    "status": "OPEN",
    "tenantOrderId": "abc-111",
    "processId": "2c4a43f2-7f69-40df-9cef-e8665012ec73",
    …
  }
}

Here, esp. the order id and the processId are of interest because they can be used for subsequent API calls. As you can see here, the status is LOCKED, so, evaluating the status field you can subscribe on the creation of locked orders.

ORDER_UNLOCKED

The is an ORDER_UNLOCKED event you can subscribed to to receive notifications, when an order is manually unlocked and ready for fulfillment.

The OrderUnlockedWebHookEvent also contains all the details about the order:

{
  "event": "ORDER_UNLOCKED",
  "eventId": "4395488122884786",
  "payload": {
    "id": "287ce844-fb3d-43f1-bc52-d667db8cbbb5",
    "status": "OPEN",
    "tenantOrderId": "abc-111",
    "processId": "2c4a43f2-7f69-40df-9cef-e8665012ec73",
    …
  }
}

The status (previously LOCKED) is now OPEN.