How to enable Returns in Fluent OMS and Fluent Store
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
27 Aug 2025
Overview
The Returns feature is available for any OMX web apps. The following guide will step through the areas of configuration to enable the Returns reference solution.Key points
- A step-by-step guide to enable reference return functionality.
- Settings setup
- Create & Assign the Instore Return Role
- Workflow Configuration (Order, returnOrder and Billing)
- Manifest Changes for Fluent Store and Fluent OMS
Settings
The following settings are required as part of the Return workflow setup:Create & Assign the Instore Return Role
Workflow Configuration
The following steps provide a reference solution of how workflows can be configured to enable Returns. The below diagram serves as a visual guide of the logical flow of these rules and how they interact across workflows to manage a Return across its entire lifecycle. Hence, we will update the order workflows and create a return order workflow and a billing workflow.
1. Configuring the Order workflow
The following supplied Returns rules can be added to the order workflow to allow a Return order to be created from an existing order.ValidateOrderQty
The`ValidateOrderQty` rule validates if a `ReturnOrder` can be created based on the order item quantity that is available to return.CreateReturnOrderFromOrder
The`CreateReturnOrderFromOrder` rule creates a return order entity to begin the process of refunding the returned items.UpdateOrderItemAttribute
The`UpdateOrderItemAttribute` rule calculates the remaining returnable quantity for the items within the order.Example Order Rulesets using the Returns rules
Using the above rules, we have assembled a sample set of rulesets, including status updates, which can be implemented into an Order workflow.If you are using the sample rulesets, please replace the`subtype` value with the order type you are implementing the rulesets against.The sample `ReturnOrder` ruleset above has a `ChangeStateGQL` rule which changes the order status to `RETURN_CREATED`. Secondly, the `OrderReturnComplete` ruleset also contains a `ChangeStateGQL` rule which upon execution changes the order status to `RETURN_COMPLETE`. To enable these rules to execute you will need to add the relevant statuses to the order workflow. The following snippet provides an example of that.2. Configuring the Return Order workflow
After creating a Return Order entity, you will need to create a workflow to manage it in its lifecycle. The following rules facilitate that process:CreateReturnFulfilment
The`CreateReturnFulfilment` rule creates a Return Fulfilment for all return items.SendEventToUpdateOrderItemAttribute
The`SendEventToUpdateOrderItemAttribute` rule updates the returnable quantity amount for each returned order item.VerifyBillingAccount
The`VerifyBillingAccount` rule verifies that a billing account exists for the Customer Returning the items.CreateBillingAccount
The`CreateBillingAccount` rule creates a Billing Account for the Customer.SendEventForReturnToBillingAccount
The`SendEventForReturnToBillingAccount` rule sends an event to the Billing Account associated with the Customer creating the Return.SendEventForReturnToOrder
The`SendEventForReturnToOrder` rule sends an event to the Order associated with the Returns Order.Example Return Order workflow
Using the above rules, we have assembled a sample Return Order Workflow. This workflow sample assumes the use of the following environment variables.`retailerID``version`
3. Configuring the Billing Account Workflow
CreateCreditMemoFromReturnOrder
The`CreateCreditMemoFromReturnOrder` rule when executed creates a credit memo for the customer billing account with the amount captured in the Return Order.SendEventForCreditMemoToReturn
The`SendEventForCreditMemoToReturn` rule sends an event from the credit memo to the return order entity.Example Billing Account workflow
Using the above rules, we have assembled a sample Billing Account Workflow. This workflow sample assumes the use of the following environment variables.`retailerID``version`
Manifest Changes for Fluent Store and Fluent OMS
1. Configure Fluent Store Base Manifest
The following changes will be required to the`fc.mystique.manifest.store` manifest.Add the Returns Plugin
Add the Returns Plugin alongside any others that exist within the manifest. See how to configure UX plugins here`{`"type": "url",
"src": "/_plugins/returns"
}
Add the Returns Reference Route
Add the Returns Reference Route alongside the others within the manifest. See Reference Routes for more information.`{`"type": "reference",
"settingName": "fc.mystique.manifest.store.fragment.returns"
}
Add the Returns Fragment
Create a new fragment called`fc.mystique.manifest.store.fragment.returns` using the same naming as the reference route added to `fc.mystique.manifest.store.json` in the previous step.The most up-to-date content for the Returns fragment can be found in the Fluent Store getting started guide.2. Configure Fluent OMS Manifests
Update OMS Base Manifest
Much like the Store manifest, the Returns plugin needs to be added to the base OMS manifest.`{`"type": "url",
"src": "/_plugins/returns"
}
Configure the Order Management Fragment
If you are not using the latest`fc.mystique.manifest.oms.fragment.ordermanagement` reference fragment, then the following additions are required.In the props of the `orders/:id/:retailerId/:ref` (Order Details) page a primary user action is required for returnOrder.Optionally add `overrides` to edit the `lodgedLocation` and `pickupLocationtext` text labels.In the following snippet lines 21-34 are the new user action configuration which should be added to the `ordermanagement` fragment. The other lines serve to demonstrate where exactly the new user action and overrides are required.Returns order management fragment changes
