Return

This guide describes how to manage product returns using the ItemReturnJob entity. For a high-level overview of the business case, refer to the introduction to returns management.

The ItemReturnJob is the current entity for processing returns. The older Return entity is deprecated and should not be used for new integrations.

Detailed endpoint specifications for creating and managing ItemReturnJob entities are available in the API reference.

Automatic ItemReturnJob creation

After the handover process is complete, the fulfillmenttools platform automatically creates a new ItemReturnJob. The system then sends a notification with the ITEM_RETURN_JOB_CREATED event.

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.

Creating an ItemReturnJob manually

An ItemReturnJob can be created manually, without a preceding handover, by calling the following endpoint:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/itemreturnjobs

{
  "processRef": "string",
  "originFacilityRefs": [
    "string"
  ],
  "status": "OPEN",
  "tenantOrderId": "string",
  "consumerAddresses": [
    {
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "houseNumber": "42a",
      "postalCode": "40764",
      "street": "Hauptstr.",
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "personalTitle": "Dr.",
      "salutation": "Frau",
      "email": "[email protected]",
      "addressType": "POSTAL_ADDRESS"
    }
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "imageUrl": "string",
        "tenantArticleId": "4711-1",
        "titleLocalized": {
          "de_DE": "Poster von Köln",
          "en_US": "Poster of cologne"
        }
      },
      "delivered": 1
    }
  ],
  "notReturnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "string",
        "tenantArticleId": "4711",
        "titleLocalized": {
          "de_DE": "Kölnisch Wasser",
          "en_US": "Cologne Water"
        }
      },
      "delivered": 1
    }
  ]
}

Returning line items

Line items are returned by creating a new ItemReturn entity within an existing ItemReturnJob. This is done using the following API call:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/itemreturnjobs/{itemReturnJobId}/itemreturns

{
  "itemReturnForCreation": {
    "status": "ANNOUNCED",
    "returnFacilityRef": "string",
    "tenantOrderId": "string",
    "returnedLineItems": [
      {
        "itemConditionComment": "Upper corner damaged",
        "tenantArticleId": "4711-1",
        "status": "OPEN"
      }
    ]
  },
  "itemReturnJobVersion": 1
}

This call creates a pre-announced 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.

Note that the status of an ItemReturnJob does not 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 by updating the refund and status fields of a specific returnedLineItem. 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.

PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems/{returnedLineItemId}

{
  "status": "OPEN",
  "refund": {
    "status": "OPEN",
    "price": {
      "value": 19.95,
      "currency": "EUR"
    }
  },
  "itemReturnJobVersion": 2
}