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
Modify quantity and article properties (except tenantArticleId)
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 modification configuration
There's an order modification configuration that controls the behaviour of the order modification feature.
Currently supported:
Enabling or disabling the modification of order line items
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:
Modifying addresses:
Modifying order line items:
Modifying multiple properties (for example, addresses and line items):
If the order has been modified by another process since you last retrieved it, you'll receive a 409 Conflict error. In this case:
Fetch the latest version of the order
Review the changes
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
Always include the current version: Use optimistic locking to prevent conflicts.
Provide meaningful comments: Help track the reason for modifications in the updateDetails history.
Use diff-based updates for line items: Only include changed items in orderLineItems array to keep the request minimal.
Be aware of process state timing: Consider the timing of your modifications relative to the fulfillment process.
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.
Monitor events: Listen to ORDER_MODIFIED events for real-time updates. See the Available events article.
Ensure proper permissions: Verify that your API credentials have the necessary permissions (ORDER_WRITE, ORDER_CONSUMER_WRITE, ORDER_LINEITEM_WRITE) for the intended modifications.
