Announced returns

Introduction

Announced returns are return requests that the customer has registered before the physical package arrives at the facility. The announcement may include reasons and item conditions. An announced return is stored in the associated item return job with the status ANNOUNCED and can be updated until confirmed.

A step-by-step functional guide is available under Products – Announced returns More item return API information can be found under REST API documentation – Item Returns

Find an item return job by order

Use the following endpoint to obtain the item return job ID for a given order (order contains only returnable items).

GET https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/itemreturnjobs?searchTerm={TENANT_ORDER_ID}&facilityId={FACILITY_ID}

Response example (excerpt):

[
  {
    "id": "job_98765",
    "status": "OPEN",
    "tenantOrderId": "ORDER_456",
    "returnableLineItems": [
      {
        "article": { 
          "tenantArticleId": "4711",
          "title": "Cologne Water"
        },
        "delivered": 1,
        "returned": 0,
        "returnable": 1
      }
    ],
    "notReturnableLineItems": [],
    "itemReturns": []
  }
]

Create an announced return

Create an item return with status ANNOUNCED within the existing item return job. To create an item return, do the following API call:

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

{
  "itemReturnForCreation": {
    "status": "ANNOUNCED",
    "returnFacilityRef": "FACILITY_123",
    "tenantOrderId": "ORDER_456",
    "scannableCodes": ["RETURN_LABEL_789"],
    "returnedLineItems": [
      {
        "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
        "status": "OPEN",
        "scannedCodes": ["CODE_123"],
        "itemConditionLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "itemConditionComment": "Upper corner damaged",
        "reasons": [
          {
            "reason": "SIZE_TOO_SMALL",
            "reasonLocalized": {
              "de_DE": "Zu klein",
              "en_US": "Too small",
              "ru_RU": "Слишком маленький"
            },
            "comment": "Upper corner damaged"
          }
        ],
        "customAttributes": {},
        "recordableAttributes": [
          {
            "group": "general",
            "keyLocalized": {
              "de_DE": "Land",
              "en_US": "Country",
              "ru_RU": "Страна"
            },
            "recordingRule": "MANDATORY",
            "value": "Germany"
          }
        ]
      }
    ]
  },
  "itemReturnJobVersion": 0
}

201 CREATED response example

{
  "id": "ret_12345",
  "created": "2025-08-11T08:30:00.000Z",
  "status": "ANNOUNCED",
  "returnFacilityRef": "FACILITY_123",
  "tenantOrderId": "ORDER_456",
  "returnedLineItems": [
    {
      "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
      "status": "OPEN",
      "itemConditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "reasons": [
        {
          "reason": "SIZE_TOO_SMALL",
          "reasonLocalized": {
            "de_DE": "Zu klein",
            "en_US": "Too small",
            "ru_RU": "Слишком маленький"
          },
          "comment": "Upper corner damaged"
        }
      ],
      "recordableAttributes": [
        {
          "group": "general",
          "keyLocalized": {
            "de_DE": "Land",
            "en_US": "Country",
            "ru_RU": "Страна"
          },
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ]
    }
  ],
  "itemReturnJobId": "job_98765"
}