Orders

To understand what exactly an order is, please read the business description of our order.

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

Create an order

Orders with the same tenantOrderId are only allowed if the previous orders are not in the status OPEN, LOCKED, or PROMISED. Cancel the previous orders first.

To create a new order at fulfillmenttools, call the following POST endpoint:

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]"
  },
  "tenantOrderId": "R456728546",
  "orderDate": "2024-01-19T08: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"
    }
  }
}

If the request was successful, it returns an HTTP 200 OK response with a body that contains some new values:

id: Every order has a unique generated ID for identification

version: Version as part of our optimistic locking mechanism

orderLineItems[].id: Each order line item has its ID

status: Every order has a status, newly posted orders always have the status OPEN

processId: A process is an entity containing every entity involved in the whole fulfilling process

created: Time at which the order was created in the platform

lastModified: Time the order was most recently modified

Modify an order

Not all properties of an order can be modified after the order has been placed. The following properties can be changed:

• Order line items

  • change quantity only

  • custom attributes of an order line itme can be changed by dedicated order line item actions POST endpoint - Doumentation is WIP

  • feature must be activated in order modification configuration

• Order Custom Attributes

• Preferred Handling time (Shipping order: desiredDeliveryTime, Click-and-Collect order: provisioningTime)

Consumer details (name, address, email) can be updated via dedicated actions using the order actions POST endpoint. (Documentation is WIP)

To modify an existing order at fulfillmenttools, call the following PATCH endpoint:

PATCH https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/orders/{orderId}

{
  "version": 9,
  "comment": "customer requested item amount increase",
  "customAttributes": {
    "attribute1":"value"
  },
  "preferredHandlingTime": "2024-05-04T13:00:00.000Z",
  "orderLineItems": [
    {
      "id":"75d37a56-8e97-4598-afe9-4523af32bc0c",
      "quantity": 100
    }
  ]
}

If the request was successful, it returns an HTTP 200 OK response with a body containing the updated order.

Please be aware that:

• An order must have at least one order line item with a quantity > 0.

• All validations that are applied during order creation are also applied during order modification.

• Every order modification triggers a re-routing of the order.

• You can provide a comment for the modification, which is part of new updateDetails field in the order.

• The user field is only set when the actorAnonymization in the GPDR configuration is set to false.

• An event is sent when an order is modified. See Available Events for more information.

{
  // ...order body
  "updateDetails": [{
    "created": "2024-05-01T10:15:30.000Z",
    "user": "[email protected]",
    "comment": "customer requested item amount increase",
    "changes": {
      "customAttributes": {
        "attribute1":"value"
      },
      "preferredHandlingTime": "2024-05-04T13:00:00.000Z",
      "orderLineItems": [
        {
          "id":"75d37a56-8e97-4598-afe9-4523af32bc0c",
          "quantity": 100
        }
      ]
    }
  }]
}

Order Modification Configuration

There is a order modification configuration that controls the behaviour of the order modification feature.

Currently supported:

• enabling or disabling the modification of order line items

GET/PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/configurations/ordermodification

{
  "version": 1,
  "allowOrderLineItemModification": true
}