Return - ItemReturnJob & Refund

More Return-API information can be found here: REST API documentation - ItemReturnJob

Be aware: Returns are deprecated and an old concept; use ItemReturnJobs instead.

To understand the business case of ItemReturnJobs, read the documentation.

ItemReturnJob is automatically created

Once the handover process is completed, the fulfillmenttools platform automatically creates a new ItemReturnJob. A notification about that will be sent 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. Regardless of whether the order was split into multiple pick jobs, all items from all handovers are in the ItemReturnJob.

Create ItemReturnJob

To create an ItemReturnJob without a handover, call 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
    }
  ]
}

Return line items

To return line items, create a new ItemReturns entity with 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 creates a pre-announced ItemReturn that can be later set to FINISHED or another status, if it is needed. The returned item must be part of the returnableLineItems array of the ItemReturnJob. Furthermore, line items can be added and updated to switch the status from OPEN to e.g. ACCEPTED. Take a look at the Returns-API for more details.

The status of one ItemReturnJob does not automatically switch to FINISHED if all returnedLineItems are set to ACCEPTED, this must be done by an API call. This action will trigger another ITEM_RETURN_JOB_UPDATED event.

Trigger Refund

To trigger a refund, with a PATCH on the returnedLineItems, the refund and status values can be changed. More information can be found in the REST API 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
}