> For the complete documentation index, see [llms.txt](https://docs.fulfillmenttools.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fulfillmenttools.com/documentation/by-pillar/order-management/order-modification.md). # Order modification The order modification feature allows users to adjust both original order details and process flows, enhancing flexibility and responsiveness in order handling. To enable order modification within Backoffice, you must edit the [remote configuration](/documentation/by-pillar/store-operations/remote-configuration.md) and set the `PROCESS_DETAILS_EDIT_ORDER_ENABLED`. You'll then need to add the required permission. The general permission `ORDER_LINEITEM_WRITE` can be used, or you can add more granular permissions. See the tables in the sectinos below to ensure that each role can only perform the specific operation it's authorized for. ## **Original order modification**

Action	Description	Conditions	Effect
Edit line items	Delete items or adjust quantities to correct errors or reflect stock/customer needs.	All associated operational entities are in the "open" state Order line item is not attached to a custom service or bundled with another item in the order The feature is activated via the order modification configuration in the REST API Each edit action requires its own permission: General write access: `ORDER_LINEITEM_WRITE` Add item: `LINE_ITEM_ADD` Delete item: `LINE_ITEM_DELETE` Increase quantity: `LINE_ITEM_QUANTITY_INCREASE` Decrease quantity: `LINE_ITEM_QUANTITY_DECREASE`	Reroute order
Add new line item	Extend the order by adding additional items.	All associated operational entities are in the "open" state Order line item is not attached to a custom service or bundled with another item in the order The feature is activated via the order modification configuration in the REST API The necessary permission `ORDER_LINEITEM_WRITE` and `LINE_ITEM_ADD` is set	Reroute order
Edit or add preferred date	Add or change the delivery/handover date.	All associated operational entities are in the "open" state The feature is activated via the order modification configuration in the REST API The necessary permission `ORDER_WRITE` is set	Reroute order
Edit custom attributes	Add or change attributes to tailor orders, for example, new routing criteria.	All associated operational entities are in the "open" state The necessary permission `ORDER_CUSTOM_ATTRIBUTES_WRITE` is set	Reroute order
Edit customer address	Correct address errors. A new shipping label might be required.	The necessary permission `ORDER_CONSUMER_WRITE` is set	If a shipping label has already been generated, it becomes obsolete and must be recreated.

### Impact of original order modifications A reroute results in the release of the inventory reservation. But an order might become unroutable if inventory is reserved for another order during the reroute process. ## **Process modification**

Action	Description	Conditions
Cancel order	Cancels all entities of an order.	All pick jobs are open No items have been picked No shipping labels requested The necessary permission `ORDER_CANCEL` is set
Force cancel order	Sets all entities to canceled regardless of processing status. Releases reserved stock. If items are already picked, manual steps are required to return items to storage and align physical inventory with system records.	Must be enabled via REST API The necessary permission `ORDER_FORCE_CANCEL` is set
Carrier change	Changes the carrier for the picking task. A new label must be generated.	Ship‑from‑store orders only Handover job is open The necessary permission `SHIPMENT_WRITE` is set
Assign order	Assigns the order to a new facility and creates a new pick job there. Deletes existing pick jobs.	Ship‑from‑store orders only All pick jobs are open No items have been picked No labels have been requested The necessary permission `PROCESS_WRITE` is set
Reroute order	Performs new routing if the current routing isn't optimal. Deletes existing pick jobs.	All pick jobs are open No items have been picked No labels have been requested The necessary permission `PROCESS_REROUTE` is set
Reroute unroutable order	Re-evaluates the order against routing rules to find an optimal path. Can be executed in bulk to process multiple unroutable orders simultaneously.	Order or articles within the order are not routable The necessary permission `ROUTING_WRITE` is set
Task reroute	Enables manual rerouting of tasks. Blocks the facility previously processing the order (if activated in the settings).	Pick job is open The necessary permission `ROUTING_WRITE` is set

## Order modification events Order modifications trigger specific events that enable tracking changes or integrating with other systems. See the complete list of [available events](/documentation/getting-started/eventing/available-events.md). ## 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](#order-modification-configuration) * See [Order Line Items Modification](#order-line-items-modification) for details * **Order custom attributes** * Can only be modified before pick job or handover job has started * **Preferred handling time** * Ship-from-store 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](#modification-restrictions-based-on-process-state) for details To modify an existing order at fulfillmenttools, call the following PATCH endpoint: ```http PATCH https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/orders/{orderId} ``` The request body can contain any combination of the modifiable properties: ```json { "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": "+49123456789", "label": "private", "type": "MOBILE" } ], "additionalAddressInfo": "2. Stock, links", "email": "max.mustermann@example.com", "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 {% hint style="warning" %} 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 {% endhint %} **Example:** ```json "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](#order-modification-configuration) for more information. {% hint style="info" %} 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. {% endhint %} ### 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](/documentation/by-pillar/order-management/gdpr-configuration.md) is set to `false`. * An event is sent when an order is modified. See [Available events](/documentation/getting-started/eventing/available-events.md) for more information. * Modification restrictions depend on the fulfillment process state (pick job, handover job). See [Modification Restrictions](#modification-restrictions-based-on-process-state) 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. ```json { // ...order body "updateDetails": [ { "created": "2024-05-01T10:15:30.000Z", "user": "customer-service@fulfillmenttools.com", "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 ```http PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/configurations/ordermodification ``` ```json { "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](/documentation/getting-started/authentication-and-authorization.md) 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` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.fulfillmenttools.com/documentation/by-pillar/order-management/order-modification.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.