fulfillmenttools
  • Welcome to the fulfillmenttools Platform Documentation
  • Getting Started
    • Setup your access to fulfillmenttools
    • Make your first API Calls
      • Add your first facility
      • Add your first listing
      • Place your first order
    • Core concepts & terminology
      • Order Flow
    • Postman Collection
    • Client SDKs
    • FAQ
  • Clients
    • Backoffice
      • First steps - Registration
      • Network view
        • Home
        • Orders
          • Unroutable orders
          • Pre-orders & Backorders
          • Order History
        • Inventory Management
          • Stock Overview
          • Channel Inventory
        • Facilities
        • Users
        • Returns
        • DOMS configuration
        • Settings
        • Analytics
          • DOMS Pages
          • Fulfillment Operations Pages
          • Inventory Pages
          • Downloads Page
      • Facility view
        • Home
        • Inbound
        • Tasks
        • Listings
        • Storage Locations
        • Facility
        • Users
    • Inventory app
      • Registration Inventory App
      • App sections
        • Inbound
        • Storage and relocation
    • Operations app
      • Android
        • Manual Registration
        • Android Enterprise Registration
        • Sections
          • Picking
            • Load Units (legacy)
            • Substitute items
            • Weighed or measured products
            • Scanning configuration
            • Picking Methods
              • Batch Picking
              • Multi Order Picking
          • Packing
          • Handover
          • Returns (legacy)
        • Printing
        • Notifications
      • Webapp
        • Packing
      • Overview features Android & Webapp
    • Technical requirements
      • Zebra Hardware Scanner Configuration
      • Honeywell Hardware Scanner Configuration
      • Supported barcodes for camera scanning
      • Requirements for fft applications
      • Zebra printer
    • Returns app
      • Handle unannounced returns
      • Handle announced returns
  • Products
    • Core Functionality
      • Process
        • External actions
      • Add and manage facilities
      • Notification Center
      • Checking on features
      • Tags and Stickers Concept
      • GDPR
      • Remote Configuration
      • Expiry
      • Target time
      • Time calculation for queries of future availabilities (LPS-calculation)
      • Interfacility Transfer
    • Carrier Management
      • Overview
        • Available Carriers
      • Concepts
        • Carrier Country Service Mapping (CCSM)
        • Non-delivery-days
        • Custom Carrier & Headless operation of Carriers
      • Providing needed data
    • Fulfillment Options
      • Fulfillability Check
      • Checkout Options
        • Available fulfillment options based on basket
        • Earliest possible delivery date
        • Available delivery dates within time-period
        • Availability for delivery date
      • Delivery Promise
    • Inventory Management
      • Configurations
      • Entities
        • Listing
        • Stock
          • Stock Properties
        • Storage Location
        • Zone
      • Global Inventory
        • Stock availability
        • Channel Inventory
        • Expected stock
        • Inbound Process
        • Reservations
        • Safety Stock
      • Inventory Control
        • Inventory Traits
        • Measurement Units
        • Outbound Inventory Tracking
        • Storage Location Recommendations
    • Order Fulfillment
      • Headless Order Fulfillment
      • Pick Jobs
      • Zone picking
      • Load Units
      • Custom Service
      • Handover Jobs
      • Add External Documents
      • Configurations
        • Picking Configuration
          • Picking methods
          • Short Pick Reasons
        • Packing Configuration
          • Packing Container Types
        • Print / Document Configuration
        • Tag Configurations
          • Parcel Tag Configuration
        • Handover Configuration
        • Operative Container Types
    • Order Routing
      • Entities
        • Ship-from-Store Orders
        • Click-and-Collect Orders
        • Locked Orders
        • Custom Services Orders
          • Simple Custom Service Order
          • Complex Custom Service Order
      • Fences
      • Ratings
      • Order Split
        • Order split - initial routing
        • Order split after shortpick
        • Item bundles
      • Reroute
      • Shape the routing with the DOMS Toolkit
      • Decision logs
    • Returns Management
      • Returns legacy
        • Available status
      • Returns 2.0
        • Return Reasons
        • Item Conditions
        • Integrating Returns with Events
    • Use Cases
      • Demand-Driven Replenishment
      • Expected stock in availability
      • Multi Order Picking
      • Interfacility transfer
      • Assigned Users
  • Connecting to fulfillmenttools
    • General Topics
      • Use external identity providers to authenticate to fulfillmenttools
        • Microsoft Entra ID / Azure Active Directory (AD)
      • Public Event Export
      • Available Regions
      • Backup Policies
    • GraphQL API
    • RESTful API
      • General Topics
        • API Release Life Cycle
        • Versioning
        • Authorization
        • Customization via Attributes
        • Update Guarantees
        • Rate Limits
        • Resource Timestamps
        • Pagination Interface
        • Localization
        • Custom Attributes
      • OpenAPI Specification
        • Swagger UI
        • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an Event
      • Available Events
      • Tutorial
    • commercetools Connect
    • Integration Tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout Options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
  • Incident Reporting
    • How to report incidents in fulfillmenttools
    • How to define incident priorities
  • Release Notes
    • Release Summary – May 2024
    • Release Summary – June 2024
    • Release Summary – July 2024
    • Release Summary – August 2024
    • Release Summary – September 2024
    • Release Summary – October 2024
Powered by GitBook
On this page
  • Item Return Job is created
  • The first return is processed and a new ItemReturn entity is created
  • Another item is returned and a second ItemReturn is added
  • ItemReturnLineItem status ACCEPTED/REJECTED
  • Trigger Refund
  • Summary

Was this helpful?

  1. Products
  2. Returns Management
  3. Returns 2.0

Integrating Returns with Events

This section provides instructions for using events to receive notifications whenever a return is processed

PreviousItem ConditionsNextUse Cases

Last updated 5 months ago

Was this helpful?

This page is outdated. Please go to our new documentation under .

The new 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 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):

{
  "event": "ITEM_RETURN_JOB_CREATED",
  "payload": {
    "id": "460c860c-8dd0-4935-ad66-b38ae24149b8",
    "version": 1,
    "status": "OPEN",
    "processRef": "02104322-06a9-4055-8bab-e91e7a6e5db0",
    "tenantOrderId": "ORDER-1234",
    "shortId": "ER8",
    "originFacilityRefs": [
      "0ff83639-8e17-4f76-910a-20971968f103"
    ],
    "returnableLineItems": [
      {
        "id": "9266db8a-b412-41f0-93d3-9e1f0979e513",
        "delivered": 1,
        "returnable": 1,
        "returned": 0,
        "article": {
          "tenantArticleId": "TG560052",
          "title": "TechGlow Smartwatch Ultra",
          "imageUrl": "https://picsum.photos/id/0/5000/3333"
        }
      },
      {
        "id": "cbe81a6f-76c8-4e19-8e2e-89e875467102",
        "delivered": 1,
        "returnable": 1,
        "returned": 0,
        "article": {
          "tenantArticleId": "NT420074",
          "title": "NovaTech Smartphone 2000 Pro",
          "imageUrl": "https://picsum.photos/id/20/3670/2462"
        }
      }
    ],
    "itemReturns": []
  },
  "eventId": "ddee67fc-296f-4d22-bbf5-55cb4db02619"
}

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:

{
  "event": "ITEM_RETURN_JOB_UPDATED",
  "payload": {
    "id": "460c860c-8dd0-4935-ad66-b38ae24149b8",
    "version": 2,
    "status": "OPEN",
    "processRef": "02104322-06a9-4055-8bab-e91e7a6e5db0",
    "tenantOrderId": "ORDER-1234",
    "shortId": "ER8",
    "originFacilityRefs": [
      "0ff83639-8e17-4f76-910a-20971968f103"
    ],
    "returnableLineItems": [
      {
        "id": "9266db8a-b412-41f0-93d3-9e1f0979e513",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "TG560052",
          "title": "TechGlow Smartwatch Ultra",
          "imageUrl": "https://picsum.photos/id/0/5000/3333"
        }
      },
      {
        "id": "cbe81a6f-76c8-4e19-8e2e-89e875467102",
        "delivered": 1,
        "returnable": 1,
        "returned": 0,
        "article": {
          "tenantArticleId": "NT420074",
          "title": "NovaTech Smartphone 2000 Pro",
          "imageUrl": "https://picsum.photos/id/20/3670/2462"
        }
      }
    ],
    "itemReturns": [
      {
        "id": "0e3db3de-100b-49dc-b63d-c4a9e99ba5f5"
        "status": "FINISHED",
        "returnFacilityRef": "0ff83639-8e17-4f76-910a-20971968f103",
        "tenantOrderId": "ORDER-1234",
        "returnedLineItems": [
          {
            "id": "118da0bd-40ae-4c48-b3e7-189505ac4d7b",
            "status": "ACCEPTED",
            "tenantArticleId": "TG560052",
            "reasons": [
              {
                "reason": "Don't like product",
                "reasonLocalized": {
                  "de_DE": "Artikel gefällt nicht",
                  "en_US": "Don't like product"
                }
              }
            ],
            "itemReturnJobLineItemRefs": [
              "9266db8a-b412-41f0-93d3-9e1f0979e513"
            ]
          }
        ]
      }
    ]
  },
  "eventId": "d55e0435-c9fb-4003-bd2f-d23bcab5b5aa"
}

What you can observe in this example:

  • The returnableLineItems array reflects the updated values of the returnable and returned fields.

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:

{
  "event": "ITEM_RETURN_JOB_UPDATED",
  "payload": {
    "id": "460c860c-8dd0-4935-ad66-b38ae24149b8",
    "version": 3,
    "status": "OPEN",
    "processRef": "02104322-06a9-4055-8bab-e91e7a6e5db0",
    "tenantOrderId": "ORDER-1234",
    "shortId": "ER8",
    "originFacilityRefs": [
      "0ff83639-8e17-4f76-910a-20971968f103"
    ],
    "returnableLineItems": [
      {
        "id": "9266db8a-b412-41f0-93d3-9e1f0979e513",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "TG560052",
          "title": "TechGlow Smartwatch Ultra",
          "imageUrl": "https://picsum.photos/id/0/5000/3333"
        }
      },
      {
        "id": "cbe81a6f-76c8-4e19-8e2e-89e875467102",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "NT420074",
          "title": "NovaTech Smartphone 2000 Pro",
          "imageUrl": "https://picsum.photos/id/20/3670/2462"
        }
      }
    ],
    "itemReturns": [
      {
        "id": "0e3db3de-100b-49dc-b63d-c4a9e99ba5f5",
        "status": "FINISHED",
        "returnFacilityRef": "0ff83639-8e17-4f76-910a-20971968f103",
        "tenantOrderId": "ORDER-1234",
        "returnedLineItems": [
          {
            "id": "118da0bd-40ae-4c48-b3e7-189505ac4d7b",
            "status": "ACCEPTED",
            "tenantArticleId": "TG560052",
            "reasons": [
              {
                "reason": "Don't like product",
                "reasonLocalized": {
                  "de_DE": "Artikel gefällt nicht",
                  "en_US": "Don't like product"
                }
              }
            ],
            "itemReturnJobLineItemRefs": [
              "9266db8a-b412-41f0-93d3-9e1f0979e513"
            ]
          }
        ]
      },
      {
        "id": "62efdc92-d5b7-4d2f-b5ea-87d4627c5463",
        "status": "FINISHED",
        "returnFacilityRef": "694cdd6c-3d59-4c0e-a051-d8c5b716df07",
        "tenantOrderId": "ORDER-1234",
        "returnedLineItems": [
          {
            "id": "01a84fdf-217c-4402-8e79-1ec279af6ad2",
            "status": "ACCEPTED",
            "tenantArticleId": "NT420074",
            "reasons": [
              {
                "reason": "Wrong delivery",
                "reasonLocalized": {
                  "de_DE": "Falsch geliefert",
                  "en_US": "Wrong delivery"
                },
                "comment": "did not order this"
              }
            ]
            "itemReturnJobLineItemRefs": [
              "cbe81a6f-76c8-4e19-8e2e-89e875467102"
            ]
          }
        ]
      }
    ]
  },
  "eventId": "37617f83-1ebe-4f81-b974-c10ae4a63bf0"
}

What you should note here:

  • A second ItemReturn was added to the itemReturns array.

  • 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 ItemReturns will not be changed - meaning, once an item has been processed you cannot remove it or change its quantity.

  • The second item in the returnableLineItems array has updated values for the returnable and returned fields.

Once all items have been returned (returnable = 0 for all returnableLineItems), processing additional returns is not possible.

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:

{
  "event": "ITEM_RETURN_JOB_UPDATED",
  "payload": {
    "id": "d2c0f718-88da-4067-949b-f2dc95d66057",
    "version": 2,
    "status": "OPEN",
    "processRef": "821a29f0-8d42-4dfa-bc91-4a112c4c62fb",
    "tenantOrderId": "ORDER-2222",
    "shortId": "DS4",
    "originFacilityRefs": [
      "aa89b8b2-ac83-4592-a36e-f4f77fde06dc"
    ],
    "returnableLineItems": [
      {
        "id": "201dde4e-adf3-4dc9-95c0-1669c47bbec0",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "CS0114141",
          "title": "CyberSense Wireless Mouse",
          "imageUrl": "https://picsum.photos/id/63/5000/2813"
        }
      }
    ],
    "itemReturns": [
      {
        "id": "ff0c2054-bbb0-4c58-9af9-84ea4b77f53b",
        "status": "FINISHED",
        "returnFacilityRef": "0ff83639-8e17-4f76-910a-20971968f103",
        "tenantOrderId": "ORDER-2222",
        "returnedLineItems": [
          {
            "id": "f338aac0-e996-4bb1-be55-82dbb19886fd",
            "status": "WAITING_FOR_INPUT",
            "tenantArticleId": "CS0114141",
            "reasons": [
              {
                "reason": "Damaged",
                "reasonLocalized": {
                  "de_DE": "Artikel beschädigt",
                  "en_US": "Damaged"
                }
              }
            ],
            "itemCondition": "Damaged",
            "itemConditionLocalized": {
              "de_DE": "Beschädigt",
              "en_US": "Damaged"
            },
            "itemReturnJobLineItemRefs": [
              "201dde4e-adf3-4dc9-95c0-1669c47bbec0"
            ]
          }
        ]
      }
    ]
  },
  "eventId": "a1be6f5f-d071-40eb-94f7-e87ce019631c"
}

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:

{
  "event": "ITEM_RETURN_JOB_UPDATED",
  "payload": {
    "id": "d2c0f718-88da-4067-949b-f2dc95d66057",
    "version": 3,
    "status": "OPEN",
    "processRef": "821a29f0-8d42-4dfa-bc91-4a112c4c62fb",
    "tenantOrderId": "ORDER-2222",
    "shortId": "DS4",
    "originFacilityRefs": [
      "aa89b8b2-ac83-4592-a36e-f4f77fde06dc"
    ],
    "returnableLineItems": [
      {
        "id": "201dde4e-adf3-4dc9-95c0-1669c47bbec0",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "CS0114141",
          "title": "CyberSense Wireless Mouse",
          "imageUrl": "https://picsum.photos/id/63/5000/2813"
        }
      }
    ],
    "itemReturns": [
      {
        "id": "ff0c2054-bbb0-4c58-9af9-84ea4b77f53b",
        "status": "FINISHED",
        "returnFacilityRef": "0ff83639-8e17-4f76-910a-20971968f103",
        "tenantOrderId": "ORDER-2222",
        "returnedLineItems": [
          {
            "id": "f338aac0-e996-4bb1-be55-82dbb19886fd",
            "status": "REJECTED",
            "tenantArticleId": "CS0114141",
            "reasons": [
              {
                "reason": "Damaged",
                "reasonLocalized": {
                  "de_DE": "Artikel beschädigt",
                  "en_US": "Damaged"
                }
              }
            ],
            "itemCondition": "Damaged",
            "itemConditionLocalized": {
              "de_DE": "Beschädigt",
              "en_US": "Damaged"
            },
            "itemReturnJobLineItemRefs": [
              "201dde4e-adf3-4dc9-95c0-1669c47bbec0"
            ]
          }
        ]
      }
    ]
  },
  "eventId": "a0d7ef90-92ba-4aa3-a2c2-934a427aebc6"
}

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:

{
  "event": "ITEM_RETURN_JOB_UPDATED",
  "payload": {
    "id": "0f27dc34-1a5d-450d-8736-ad6b426ae360",
    "version": 6,
    "status": "OPEN",
    "processRef": "0cf08608-e82f-403a-a7d6-dd50d281f268",
    "tenantOrderId": "ORDER-3333",
    "shortId": "NT5",
    "originFacilityRefs": [
      "0ff83639-8e17-4f76-910a-20971968f103"
    ],
    "returnableLineItems": [
      {
        "id": "f00c0b11-d6be-4d35-881a-91ff3b0db162",
        "delivered": 1,
        "returnable": 0,
        "returned": 1,
        "article": {
          "tenantArticleId": "PP591833623",
          "title": "PowerPro USB Stick 512 GB",
          "imageUrl": "https://picsum.photos/id/17/2500/1667",
          "prices": [
            {
              "pricePerUnit": 49.95,
              "currency": "EUR"
            }
          ]
        }
      }
    ],
    "itemReturns": [
      {
        "id": "0e3db3de-100b-49dc-b63d-c4a9e99ba5f5",
        "status": "FINISHED",
        "returnFacilityRef": "0ff83639-8e17-4f76-910a-20971968f103",
        "tenantOrderId": "ORDER-3333",
        "returnedLineItems": [
          {
            "id": "7e08e8d3-3e56-4cb4-8ccd-7314172b96e0",
            "status": "ACCEPTED",
            "tenantArticleId": "PP591833623",
            "reasons": [
              {
                "reason": "Wrong delivery",
                "reasonLocalized": {
                  "de_DE": "Falsch geliefert",
                  "en_US": "Wrong delivery"
                }
              }
            ],
            "itemReturnJobLineItemRefs": [
              "f00c0b11-d6be-4d35-881a-91ff3b0db162"
            ],
            "refund": {
              "status": "CLOSED",
              "price": {
                "value": 49.95,
                "currency": "EUR"
              },
              "percent": null
            }
          }
        ]
      }
    ]
  },
  "eventId": "ecff2978-2c7d-4b11-801f-625ea8ff3494"
}

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.

The itemReturns array contains the first ItemReturn with details about the returned items in the returnedLineItems array. The status of the ItemReturn is FINISHED because the process has been completed in the Returns app. For each returned item, there can be return and comments, and an item 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 is ACCEPTED.

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 call with FinishItemReturnJob payload. This action will trigger another ITEM_RETURN_JOB_UPDATED event.

Fore more details and information, refer to the of the API specification.

https://docs.fulfillmenttools.com/documentation
Returns
Eventing
reasons
condition
updateItemReturnJob
relevant sections