API documentationIncident ManagementFeedback
Edit

Placing orders

More information about the Orders API is available in the REST API documentation for Orders.

What is an order?

An order in the fulfillmenttools platform is the entry point for the fulfillment process. The platform consumes the following information from an order object:

  • The customer's location

  • The time the order was placed

  • The line items of the order, including:

    • article (title and tenantArticleId)

    • quantity

This is the minimum information the platform needs for order fulfillment; however, more information can be provided. For example, an order line item can contain a list of scannable codes that must be scanned when the item is picked in a facility. Furthermore, it is recommended to configure the deliveryPreferences for the order.

Placing the order

Placing an order requires the information mentioned above and a POST call to the orders endpoint. This call might look like the following example.

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": "[email protected]"
  },
  "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"
}

Compared to a listing, the order payload contains less information about the articles. If an active listing exists for the provided tenantArticleId, the system automatically maps the article details, since these details were already provided when the listings were created.

201 CREATED response

The response contains several properties not present in the original request:

  • id: A unique identifier for the order.

  • version: The version of the order, used as part of the platform's optimistic locking mechanism.

  • orderLineItem.id: A unique identifier for each order line item.

  • status: The status of an order. A newly created order always has the status OPEN.

  • tags: A separate entity that can be helpful when configuring the Distributed Order Management System (DOMS) ruleset. More information is provided later in the tutorial.

  • processId: A process groups all entities involved in a fulfillment. This field stores the unique identifier of that process.

  • created: The timestamp when the order was created in the platform.

  • lastModified: The timestamp of the last modification to the order.

What to do after successfully placing the first order?

After successfully testing order placement, it is recommended to implement a solution that receives incoming orders from shop systems, transforms the data into an OrderForCreation object, and posts it to the fulfillmenttools platform.

While a custom software project is one possibility, fulfillmenttools provides a Software Development Kit (SDK) for TypeScript. Additionally, a commercetools certified connector is available in the commercetools marketplace. It is also possible to utilize Low-Code platforms like n8n or an integration platform like Patchworks.

Last updated