Announced returns

Introduction

Announced returns are return requests that a customer has registered before the physical package arrives at the facility. The announcement may include details such as reasons and item conditions. The system stores an announced return in the associated item return job with the status ANNOUNCED. This job can be updated until it is confirmed.

For a step-by-step functional guide, refer to the Announced Returns documentation.

Find an item return job by order

Use the following endpoint to obtain the item return job ID for a given order. This applies to an order that contains only returnable items.

GET https://{YOUR-TENANT-NAME}.api.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

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

POST https://{YOUR-TENANT-NAME}.api.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
}

Example 201 Created response

{
  "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"
}