Returns
This article focuses on the returns process for developers. For information on the returns in the store operations process, see the Returns app section.
A return is when a consumer sends a purchased product back to the retailer for a refund, exchange, or store credit. The return process typically involves either the consumer physically bringing the items to the store or initiating an online return.
There are two types of return:
Announced returns (the consumer notifies the retailer in advance about the return)
Unannounced returns (the consumer returns an item without prior notification)
For both types, there needs to be an item return job with the potential items to be returned from the original order.
Item return job
An itemReturnJob is the main entity in the returns process. It contains all potential itemReturns associated with a placed order. It encompasses all items eligible for return (and those not eligible) and tracks the items actually returned. During interactions with the itemReturnJob, validations ensure that only items handed over in the given order can be returned in the handed-over quantities.
An itemReturnJob is automatically created after the handover process. fulfillmenttools then sends a notification with the ITEM_RETURN_JOB_CREATED event. If the handover feature isn't used, the itemReturnJob can be created via the item return jobs REST API.
The initial status of the itemReturnJob is OPEN. The returnableLineItems list contains all items from the handover that are eligible for return. The itemReturnJob includes all items from all handovers related to the original order, even if the order was split into multiple pick jobs.
Use the endpoint below to get all item return jobs:
GET https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/itemreturnjobsItem return
An itemReturn represents all items actually returned within the associated itemReturnJob. It's imperative to have a valid itemReturnJob before creating an itemReturn.
While adding or updating an itemReturn within an existing itemReturnJob, item validations ensure that the returned quantity doesn't exceed the delivered and previously returned amounts.
Line items are returned by creating a new itemReturn entity within an existing itemReturnJob. This is done using the following API call:
This call creates a preannounced itemReturn with an initial status OPEN, which can be updated later as required. Each returned item must be part of the returnableLineItems array of the parent itemReturnJob. The request must also include the current itemReturnJobVersion to prevent concurrent modifications.
The status of an itemReturnJob doesn't automatically change to FINISHED, even if all of its returnedLineItems are ACCEPTED. The itemReturnJob status must be updated explicitly via an API call. This action triggers an ITEM_RETURN_JOB_UPDATED event.
Triggering a refund
A refund is triggered when the refund and status fields of a specific returnedLineItem are updated. This is accomplished using the following PATCH request, which requires the current itemReturnJobVersion. For more details, refer to the update returned line item endpoint documentation.
You can also trigger the refund event via Backoffice. You'll need to have the allowTriggerRefund setting in the return configuration set to true to do this.
Returnable and non-returnable items
As some items can't be returned for various reasons (customized items, special offers, and so on), an itemReturnJob has two arrays of items: returnableItems and notReturnableItems. These items represent those that are returnable and those that are not.
In the case of an itemReturnJob being created automatically in the designated workflow, both arrays are filled automatically as well.
An item will be placed in the notReturnableItems array if it was part of a related service job that with the itemsReturnable flag set to false. Otherwise, it will be placed in the returnableItems array.
If, during the handover process, items are marked as handed over by setting the handedOverQuantity value to at least 1, then those items will populate one of those arrays. The handedOverQuantity sets the returnable field.
If there is no handover job, or none of the handover job's items have a handedOverQuantity set to at least 1, the arrays will be populated with the items from the related pick job. In this case, the returnable attribute is set by the picked quantity of the items in the pick job.
You can move items from one array to another by using the corresponding actions.
Line items can only be moved if the itemReturns array of the corresponding ItemReturnJob is empty and if the returned item's value to move is 0.
Return configuration
The return configuration endpoint lets you provide default inputs for your returns. These inputs are then displayed in the Returns app and Backoffice. These can be for:
The example below shows the endpoint you need to use to update the configuration, as well as an example request including all three options.
Return reasons
Return reasons help you specify why a consumer has returned certain items as you process the return.
For example, you could add the reasons below to the return configuration:
Item doesn't fit
Item didn't match description
Item damaged
The reasons can be passed while creating an itemReturn through the API. Having default reasons is optional for passing reasons into an itemReturn.
Default values for return reasons in the backend
Default values for return reasons in the backend aren't provided. However, it's possible to manage return reasons on the client side. For example, in the Returns app, the default value return reason is "no reason". If no additional reasons are specified in the backend, the return reasons will not be displayed.
API users can use the predefined return reasons or provide their own when creating or updating the itemReturnLineItem of an itemReturn.
Returned item conditions
Upon receiving the returned item, the item's condition is assessed, eligibility is verified under the return policy, and a suitable resolution is provided (for example, a refund or store credit). This requires the ability to create a return manually.
When accepting returned items, the condition of the items can be defined. In the Returns app, the default value for conditions is set to "not damaged". However, there is no default value defined in the backend.
Localized itemConditions can be added to the returnConfiguration via return configuration REST API.
The translation depends on the locale of the user using this endpoint and the tenantLocaleConfiguration.
Decision reasons
Decision reasons allow staff to specify why a returned item was accepted, rejected, or put on hold when setting the status of a returned line item.
The reasons can be passed while updating a returned line item through the API. Having predefined reasons for decisions is optional, when setting the status of a returned line item.
Default values for decision reasons in the backend
Default values for decision reasons in the backend aren't provided. However, it's possible to manage decision reasons on the client side. If no decision reasons are configured in the backend, none will be displayed.
API users can use the predefined decision reasons or provide their own when updating the status of a returnedLineItem.
Announced returns
Announced returns are return requests that a consumer has registered before the physical package arrives at the facility. Announced returns include the items and details provided by the consumer, such as return reason and item condition.
The return announcement is transferred from the shop and an itemReturn is created in the associated itemReturnJob with the status ANNOUNCED. This job can be updated until it is confirmed.
These details are made available in Backoffice and the Returns app, where announced returns can be searched for, optionally using a barcode from the return label if provided. Furthermore, the user is able to check and, if necessary, edit those details and confirm the return.
When confirming the return, the status changes from ANNOUNCED to COMPLETED, and no further changes are possible after confirmation.
Create an announced return
To create an announced return and complete it, follow the steps below.
This example only contains returnable items.
Find the itemReturnJobId for the order
Query the GET endpoint using the tenantOrderId and facilityId
From the response, take the id for the matching the tenantOrderId as the itemReturnJobId.
Create the announced return
Create an announced return using the below endpoint. An announced return must have the status of ANNOUNCED.
You need to include the reference of the facility the item(s) are being returned to in the returnFacilityRef, as well as at least one entry in returnedLineItems.
Each returned line item must include the tenantArticleId and a line item status (for example, OPEN).
itemConditionLocalized and reasons are optional.
You can check the return in Backoffice. Open the Network view, and select Returns in the sidebar. Then, filter by Announced in the Return status. You should see your newly created return job in the table.
Edit any information prior to confirmation (optional)
Edits can be made in the Returns app. You can:
Adjust quantities
Replace or correct items within the same order
Update reasons or conditions (if applicable)
Add missing items from the same order, if necessary
Confirm the return using the Returns app
Review the summary of items and details
Confirm the return
When confirming the return, the status changes from
ANNOUNCEDtoCOMPLETEDand no further changes are possible after confirmation
Unannounced returns
An unannounced return is when a consumer returns an item without prior notification. This usually happens in a store. You can use the Returns app to manage the return process. See the Returns app article for more information.
Last updated