Returns 2.0

A return signifies our process where a customer sends a purchased product back, seeking a refund, exchange, or store credit. This occurs when a customer is dissatisfied, changes their mind, or encounters issues like defects, incorrect sizing, or incompatibility. The return process typically involves the customer physically bringing the item to our store or initiating an online return.

Upon receiving the returned item, we enable the assessment of the item's condition, check eligibility based on our return policy, and then provide a suitable resolution—be it a refund or store credit. This requires us to have the capability to manually create the return.

The specifics of our return policy, including time limits, condition requirements, and refund methods, may vary.


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, and only in the quantities available.

For user convenience, the ItemReturnJob presents the available returnable items along with a summary of returned items in a single easily readable line item.


   returnableLineItems: [
        delivered: 5,
        returned: 3,
        returnable: 2,

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 methods.

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.


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.

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 ItemReturnStatusChange

  • Replace items via ItemReturnReplaceReturnedLineItemsAction

  • Remove the ItemReturn from the ItemReturnJob using DeleteItemReturnAction

Last updated