Returns
Integrating Returns
ItemReturnJob
An ItemReturnJob serves as a container for all potential ItemReturns associated with a placed Order. It encompasses all items eligible for return and tracks actual returned ItemReturns, including the returned items within them.
During interactions with the ItemReturnJob, validations ensure that only items purchased in the given order can be returned in the purchased quantities.
The ItemReturnJob presents the available returnable items along with a summary of returned items in a single easily readable line item.
Example:
The values for returned and returnable are dynamically calculated, considering the included ItemReturns.
An ItemReturnJob is automatically generated through the designated Workflow after the Handover process. If the Handover Feature isn't utilized, the ItemReturnJob can be created via API.
All created ItemReturnJobs are accessible through this API call, with various filtering parameters available for refinement.
Alternatively, you can retrieve details of a specific ItemReturnJob via this API call.
To update the Status of an ItemReturnJob, utilize the ItemReturnJobStatusChangeAction API Action:
Once an ItemReturnJob is established, ItemReturns can be appended.
ItemReturn
An ItemReturn represents all items actually returned within the associated ItemReturnJob. It is 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.
To initiate the creation of a new ItemReturn, utilize the AddItemReturnAction API Action.
For updating an existing ItemReturn, utilize the following API Actions:
Change the Status via
ItemReturnStatusChangeReplace items via
ItemReturnReplaceReturnedLineItemsActionRemove the
ItemReturnfrom theItemReturnJobusingDeleteItemReturnAction
Returned item conditions
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 back end.
Localized itemConditions can be added to the returnConfiguration via API.
The translation depends on the locale of the user using this endpoint and the tenantLocaleConfiguration as a fallback.
A user of our API can use these predefined conditions or provide their own ones when creating or updating itemReturnLineItem of an ItemReturn.
The localized condition can be provided like this example:
When getting this ItemReturn via REST oder GQL, you will receive an additional field called itemCondition which contains only the localized value. This translation depends on the users locale.
Return reasons should help our customers to specify why certain items have been returned by the customer while creating an ItemReturn. In order to get pre-defined return reasons, these reasons can be added to the given ReturnConfiguration (1)
These reasons can be passed while creating an ItemReturn through the API. Having default reasons is optional and not mandatory for passing reasons into an ItemReturn. (2)
Default values for return reasons in the backend are not provided; however, it is possible to manage them on the client side. Like we are doing it with our app by setting the default value for return reason to "no reason". If no additional reasons are specified through the backend, the return reasons will not be displayed.
Return Reasons
Adding predefined return reasons
You can add translatable availableReturnReasons to the returnConfiguration via API.
The translation depends on the locale of the user using this endpoint and the tenantLocaleConfiguration as a fallback.
Using return reasons in ItemReturns
A user of our API can use this predefined return reasons or provide their own ones when creating or updating the ItemReturnLineItem of an ItemReturn.
The localized return reason can be provided like this example:
When getting this ItemReturn via REST oder GQL, you will receive an additional field called reason which contains only the localized value. This translation depends on the users locale.
Getting and setting these values via REST:
Integrating Returns with Events
The returns module offers a powerful yet flexible way to process incoming returns, mark the returned items, capture return reasons and item condition. Here we will show how you can process this information and which events come into play.
In order to receive notifications for new or updatedItemReturnJobs, you need to set up subscriptions for the event types ITEM_RETURN_JOB_CREATED and ITEM_RETURN_JOB_UPDATED. Please refer to the documentation on Eventing for detailed instructions on setting up subscriptions via the API.
Item Return Job is created
Once the handover process is completed, the platform automatically creates a new ItemReturnJob entity. You will receive a notification through the ITEM_RETURN_JOB_CREATED event.
The initial status of the ItemReturnJob is OPEN. The returnableLineItems array contains all items from the order that are eligible for return. Regardless of whether the order was split into multiple pick jobs, you will always be able to process all items from the entire order. The itemReturns array is empty as no items have been returned yet.
Here's an example (some fields omitted for better readability):
The first return is processed and a new ItemReturn entity is created
Let's imagine the customer has sent back an item to the shop where the incoming return is now processed with the Returns App. Here's an example for the ITEM_RETURN_JOB_UPDATED event:
What you can observe in this example:
The
returnableLineItemsarray reflects the updated values of thereturnableandreturnedfields.The
itemReturnsarray contains the firstItemReturnwith details about the returned items in thereturnedLineItemsarray. The status of theItemReturnisFINISHEDbecause the process has been completed in the Returns app. For each returned item, there can be return reasons and comments, and an item condition based on your configuration. This will help you to capture individual reasons and quality levels for each returned line item. The status of the returned line item isACCEPTED.
Another item is returned and a second ItemReturn is added
Continuing with our example, the customer has also returned the second item and the return was received and processed. The ITEM_RETURN_JOB_UPDATED event will include another ItemReturn in the itemReturns array:
What you should note here:
A second
ItemReturnwas added to theitemReturnsarray.If you look closely, you will see that the second item return has a different
returnFacilityRef. This is to show that it is possible to process returns in different facilities (e.g. customer returns one item in the shop and the other is sent back to central returns facility).Already existing
ItemReturnswill not be changed - meaning, once an item has been processed you cannot remove it or change its quantity.The second item in the
returnableLineItemsarray has updated values for thereturnableandreturnedfields.
Once all items have been returned (returnable = 0 for all returnableLineItems), processing additional returns is not possible.
Currently, the status of the ItemReturnJob does not automatically switch to FINISHED. This functionality is planned for future development. However, you can update the status through the API using the updateItemReturnJob call with FinishItemReturnJob payload. This action will trigger another ITEM_RETURN_JOB_UPDATED event.
ItemReturnLineItem status ACCEPTED/REJECTED
In the next example we will process a new order with different items. When processing the incoming return in the Returns app, the user can also request an additional quality check to be performed for the received goods. This functionality is particularly useful for high-valued goods that require a more thorough inspection of their quality.
These line items will have status of WAITING_FOR_INPUT as you can see in the example below:
Once the quality check has been performed, an item can either be accepted or rejected. This decision can be made through actions in the Backoffice or a corresponding mechanism. As a result, another ITEM_RETURN_JOB_UPDATED event will be triggered, and the status of the line item will be updated accordingly. For example, if a line item is rejected, the status will be REJECTED. Here's an example:
Trigger Refund
The final example shows an ITEM_RETURN_JOB_UPDATED event that is triggered once a refund process has been started in the Backoffice or through a corresponding API call. Here you can see the details for the selected line item in the refund property:
Summary
In your integration with the fulfillmenttools platform, you can evaluate the status of ItemReturns and ItemReturnLineItem to initiate the necessary follow-up processes. For example, you might need to start a refunding process or take other appropriate actions based on the order and return status. The availability of different status codes at each level assists you in performing the right actions for the order at the right time.
Fore more details and information, refer to the relevant sections of the API specification.
Last updated
