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://{projectId}.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

  • Modify quantity and article properties (except tenantArticleId)

  • Add new line items or remove existing ones

  • Feature must be activated in order modification configuration

  • See Order Line Items Modification for details

• Order custom attributes

  • Can only be modified before pick job or handover job has started

• Preferred handling time

  • Shipping orders: Updates desiredDeliveryTime

  • Click-and-Collect orders: Updates provisioningTime

  • Can only be modified before pick job or handover job has started

• Consumer details/addresses

  • Generally modifiable at any time

  • Changes to delivery addresses (POSTAL_ADDRESS or PARCEL_LOCKER) only allowed before handover job has started

  • See Modification Restrictions for details

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

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

The request body can contain any combination of the modifiable properties:

{
  "version": 1,
  "comment": "Customer requested address correction and item updates",
  "customAttributes": {
    "customerSpecialHandling": "voucher",
    "internalNote": "VIP customer"
  },
  "orderLineItems": [
    {
      "id": "existing-orderlineitem-id",
      "quantity": 5,
      "article": {
        "title": "Updated Product Title",
        "imageUrl": "https://example.com/updated-image.jpg"
      }
    },
    {
      "quantity": 2,
      "article": {
        "tenantArticleId": "5020064",
        "title": "Wandtattoo Stadion",
        "imageUrl": "https://d358g9injarr4u.cloudfront.net/res/product_1000/343f4569-66bb-4b0c-aa2b-20011a51b620.jpg",
        "attributes": [
          {
            "category": "descriptive",
            "priority": 100,
            "key": "Maße",
            "value": "70 x 50 cm"
          },
          {
            "category": "descriptive",
            "priority": 200,
            "key": "Beschreibung",
            "value": "Wandtattoo in Ziegelwand-Optik, Mit tollem Blick aufs Stadion"
          }
        ]
      }
    }
  ],
  "addresses": [
    {
      "salutation": "Herr",
      "personalTitle": "Dr.",
      "firstName": "Max",
      "lastName": "Mustermann",
      "street": "Musterstraße",
      "houseNumber": "123",
      "postalCode": "50667",
      "city": "Köln",
      "country": "DE",
      "province": "DE-NW",
      "phoneNumbers": [
        {
          "value": "[phone]",
          "label": "private",
          "type": "MOBILE"
        }
      ],
      "additionalAddressInfo": "2. Stock, links",
      "email": "[email protected]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.9375,
        "lon": 6.9603
      }
    }
  ],
  "preferredHandlingTime": "2027-05-04T13:00:00.000Z"
}

Order line items modification

Order line items can be modified in three ways:

1. Update existing item: Provide the id of the order line item

   • You can change the quantity

   • You can modify article properties (for example, title, imageUrl, attributes)

   • The tenantArticleId can't be modified

2. Add new item: Omit the id field

   • Provide complete article object with tenantArticleId

   • Specify desired quantity

   • Article attributes are optional

   • Same validation rules as order creation apply

3. Remove item: Set quantity to 0 for an existing order line item

   • At least one order line item must remain in the order

The orderLineItems array works as a diff/patch:

• Only include the order line items you want to change or add

• Order line items not included in the request remain unchanged

• Duplicate tenantArticleId values aren't supported

Example:

"orderLineItems": [
  {
    "id": "existing-item-id",
    "quantity": 5,
    "article": {
      "title": "Updated Product Title",
      "imageUrl": "https://new-image-url.com/image.jpg"
    }
  },
  {
    "quantity": 2,
    "article": {
      "tenantArticleId": "NEW-ARTICLE-123",
      "title": "New Product",
      "attributes": [
        {
          "category": "descriptive",
          "key": "Color",
          "value": "Blue"
        }
      ]
    }
  },
  {
    "id": "remove-this-item-id",
    "quantity": 0
  }
]

Modification restrictions based on process state

Not all order properties can be modified at all times. Depending on the fulfillment process state, certain modifications are restricted:

Consumer/addresses

Generally modifiable at any time, except:

• Changes to delivery addresses (addresses with addressType: POSTAL_ADDRESS or addressType: PARCEL_LOCKER)

• Changes to facilityRef

• Changes to tenantFacilityId

These modifications are only allowed before a handover job has started.

Custom attributes

Can only be modified when no pick job has started and no handover job has started.

Preferred handling time

The preferredHandlingTime field updates different properties depending on the order type:

• Shipping orders: Updates desiredDeliveryTime in deliveryPreferences.shipping

• Click-and-Collect orders: Updates provisioningTime in the facility preferences

Can only be modified when no pick job has started and no handover job has started.

Order line items

Requires the order modification configuration flag allowOrderLineItemModification to be set to true.

See Order modification configuration for more information.

There's no automated way to query the pick job or handover job status before attempting a modification. Consider the timing of your modifications and handle potential errors appropriately.

Response

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

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.

• Rerouting behavior:

  • Modifications to orderLineItems, customAttributes, or preferredHandlingTime trigger automatic rerouting of the order.

  • Modifications to consumer details or addresses don't trigger rerouting.

• 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.

• Modification restrictions depend on the fulfillment process state (pick job, handover job). See Modification Restrictions above.

• The orderLineItems array works as a diff. Only include items you want to modify, add, or remove. Other items remain unchanged.

• Duplicate tenantArticleId values within a single order aren't supported.

• To remove an order line item, set its quantity to 0.

• The tenantArticleId of an existing order line item can't be changed.

{
  // ...order body
  "updateDetails": [
    {
      "created": "2024-05-01T10:15:30.000Z",
      "user": "[email protected]",
      "comment": "Customer requested address correction and item updates",
      "changes": {
        "customAttributes": {
          "customerSpecialHandling": "voucher",
          "internalNote": "VIP customer"
        },
        "preferredHandlingTime": "2027-05-04T13:00:00.000Z",
        "orderLineItems": [
          {
            "id": "75d37a56-8e97-4598-afe9-4523af32bc0c",
            "quantity": 5
          }
        ],
        "addresses": [
          {
            "street": "Musterstraße",
            "houseNumber": "123",
            "postalCode": "50667",
            "city": "Köln",
            "country": "DE",
            "addressType": "POSTAL_ADDRESS"
          }
        ]
      }
    }
  ]
}

Order modification configuration

There's an order modification configuration that controls the behavior of the order modification feature.

Currently supported:

• Enabling or disabling the modification of order line items

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

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

Authorization for order modification

Different order modification operations require specific permissions:

Required permissions

• ORDER_WRITE: Required for all order modifications

• ORDER_CONSUMER_WRITE: Additionally required when modifying consumer details or addresses

• ORDER_LINEITEM_WRITE: Additionally required when modifying order line items

Permission examples

Modifying only custom attributes or preferred handling time:

Required: ORDER_WRITE

Modifying addresses:

Required: ORDER_WRITE + ORDER_CONSUMER_WRITE

Modifying order line items:

Required: ORDER_WRITE + ORDER_LINEITEM_WRITE

Modifying multiple properties (for example, addresses and line items):

Required: ORDER_WRITE + ORDER_CONSUMER_WRITE + ORDER_LINEITEM_WRITE

See the Authorization article for more information.

Order modification error handling

Optimistic locking conflicts

If the order has been modified by another process since you last retrieved it, you'll receive a 409 Conflict error. In this case:

1. Fetch the latest version of the order

2. Review the changes

3. Retry your modification with the updated version number

Validation errors

All validations from order creation also apply to modifications:

• At least one order line item must remain (quantity > 0)

• Duplicate tenantArticleId values aren't allowed

• All required fields must be present and valid

Process state restrictions

If you attempt a modification that is not allowed in the current process state (for example, changing the delivery address after handover has started), you'll receive an error response. Since there's no automated way to query the process state beforehand, handle these errors appropriately in your integration.

Best practices for order modification

1. Always include the current version: Use optimistic locking to prevent conflicts.

2. Provide meaningful comments: Help track the reason for modifications in the updateDetails history.

3. Use diff-based updates for line items: Only include changed items in orderLineItems array to keep the request minimal.

4. Be aware of process state timing: Consider the timing of your modifications relative to the fulfillment process.

5. Understand re-routing behavior: Modifications to order line items, custom attributes, or preferred handling time trigger automatic re-routing. Consumer/address updates do not trigger re-routing.

6. Monitor events: Listen to ORD