Returns endpoints

Get return configuration

get

Returns the current return configuration for the tenant.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Return Configuration

application/json

LocalizedReturnConfiguration

activebooleanRequiredDeprecated

Enable or disable legacy returns. Use returnTypeConfiguration instead

Default: trueExample: true

allowTriggerRefundbooleanOptional

If true, a refund can be triggered. If false, the endpoints to trigger a refund are disabled.

Default: false

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

get/api/configurations/return

GET /api/configurations/return HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "allowTriggerRefund": false,
  "availableDecisionReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "context": [
        {
          "type": "ITEM_RETURN_LINE_ITEM_STATUS",
          "values": [
            "ACCEPTED"
          ]
        }
      ],
      "reason": "Item damaged"
    }
  ],
  "availableItemConditions": [
    {
      "conditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "condition": "Damaged"
    }
  ],
  "availableReturnReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "identifier": "A",
      "reason": "Damaged"
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "lastModified": "2026-06-17T12:00:00.000Z",
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "version": 1
}

Create return note

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

localestringOptional

Provide the localized values for the return note. If not provided the default locale is used. For example de_DE.

Body

ReturnNote

qrCodeContentstringOptional

Responses

201

Successfully created the return note.

application/pdf

ReturnNote

qrCodeContentstringOptional

401

Your user is not allowed to operate against this API instance

application/pdf

403

Your user, although recognized, is not authorized to use this endpoint

application/pdf

post/api/returnnotes

POST /api/returnnotes HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 744

{
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddress": {
    "city": "Langenfeld",
    "companyName": "OC Fulfillment GmbH",
    "firstName": "Maxine",
    "houseNumber": "42a",
    "lastName": "Muller",
    "personalTitle": "Prof.",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddresses": [
    {
      "city": "Langenfeld",
      "companyName": "OC Fulfillment GmbH",
      "firstName": "Maxine",
      "houseNumber": "42a",
      "lastName": "Muller",
      "personalTitle": "Prof.",
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "items": [
    {
      "id": "text",
      "quantity": 1,
      "substitutes": "text",
      "title": "text"
    }
  ],
  "orderInformation": {
    "orderDate": "2020-02-03T08:45:50.525Z",
    "orderNumber": "R456728546"
  },
  "qrCodeContent": "text"
}

{
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddress": {
    "city": "Langenfeld",
    "companyName": "OC Fulfillment GmbH",
    "firstName": "Maxine",
    "houseNumber": "42a",
    "lastName": "Muller",
    "personalTitle": "Prof.",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddresses": [
    {
      "city": "Langenfeld",
      "companyName": "OC Fulfillment GmbH",
      "firstName": "Maxine",
      "houseNumber": "42a",
      "lastName": "Muller",
      "personalTitle": "Prof.",
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "items": [
    {
      "id": "text",
      "quantity": 1,
      "substitutes": "text",
      "title": "text"
    }
  ],
  "orderInformation": {
    "orderDate": "2020-02-03T08:45:50.525Z",
    "orderNumber": "R456728546"
  },
  "qrCodeContent": "text"
}

Call item return action

post

Applies an action to an Item Return. Check ItemReturnActionsParameters for available actions.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnIdstringRequired

Body

Responses

200

Updated entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

post/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions

POST /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "itemReturnJobVersion": 1,
  "name": "AnnounceItemReturn"
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Get return note config

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Return note config could be found in response body.

application/json

Return Note Configuration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

displayPageLabelbooleanOptional

Determines if the page label should be shown

Default: false

idstringRequiredExample: delivery-note

logoUrlstringOptional

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

Entity not found

application/json

get/api/configurations/returnnote

GET /api/configurations/returnnote HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "articleIdLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "articleTitleLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "disclaimer": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "disclaimerHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "displayPageLabel": false,
  "headline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "id": "delivery-note",
  "logoUrl": "text",
  "orderDateLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "orderNumberLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pageLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pdfBackgroundConfiguration": {
    "firstPageBackgroundFileUrl": "text",
    "followingPageBackgroundFileUrl": "text"
  },
  "quantityLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanation": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanationHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "substituteText": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Update return note config

put

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

ReturnNoteConfigurationForUpsert

displayPageLabelbooleanOptional

Determines if the page label should be shown

Default: false

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

Responses

200

The return note configuration was successfully updated.

application/json

Return Note Configuration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

displayPageLabelbooleanOptional

Determines if the page label should be shown

Default: false

idstringRequiredExample: delivery-note

logoUrlstringOptional

201

The return note configuration was successfully created.

application/json

400

Invalid input. See response for details

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

put/api/configurations/returnnote

PUT /api/configurations/returnnote HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 4378

{
  "articleIdLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "articleTitleLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "disclaimer": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "disclaimerHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "displayPageLabel": false,
  "headline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "logo": {
    "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
    "name": "example.pdf"
  },
  "orderDateLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "orderNumberLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pageLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pdfBackgroundConfiguration": {
    "firstPageBackgroundFile": {
      "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
      "name": "example.pdf"
    },
    "followingPageBackgroundFile": {
      "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
      "name": "example.pdf"
    }
  },
  "quantityLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanation": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanationHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "substituteText": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "version": 42
}

{
  "articleIdLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "articleTitleLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "disclaimer": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "disclaimerHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "displayPageLabel": false,
  "headline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "id": "delivery-note",
  "logoUrl": "text",
  "orderDateLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "orderNumberLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pageLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "pdfBackgroundConfiguration": {
    "firstPageBackgroundFileUrl": "text",
    "followingPageBackgroundFileUrl": "text"
  },
  "quantityLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanation": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonExplanationHeadline": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "returnReasonLabel": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "substituteText": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Get item return

get

Returns a specific item return for a given item return job.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnIdstringRequired

id of the item return you want to read

Responses

200

Get a specific item return

application/json

ItemReturn

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

parcelRefsstring[] · max: 50Optional

references the parcel

Example: 672f3f72-b5d3-47c7-941c-9af5348e3cd7

returnFacilityRefstringRequired

scannableCodesstring[] · max: 50Optional

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptionalDeprecated

deprecated: will be automatically deducted from related itemReturnJob

Example: MY_ORDER_ID

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

get/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}

GET /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "created": "2020-02-03T08:45:51.525Z",
  "customAttributes": {},
  "id": "text",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
  "returnedLineItems": [
    {
      "itemConditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "customAttributes": {},
      "decisionReason": {
        "reasonLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "comment": "Upper corner damaged",
        "reason": "text"
      },
      "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
      "itemCondition": "Damaged",
      "itemConditionComment": "Upper corner damaged",
      "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
      "reasons": [
        {
          "reasonLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "comment": "Upper corner damaged",
          "reason": "text"
        }
      ],
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "refund": {
        "percent": 80.6,
        "price": {
          "currency": "EUR",
          "value": 20.55
        },
        "status": "OPEN"
      },
      "scannedCodes": [
        "text"
      ],
      "status": "OPEN",
      "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
    }
  ],
  "returnFacilityRef": "text",
  "scannableCodes": [
    "text"
  ],
  "status": "ANNOUNCED"
}

Update returned line items

put

Replace returned line items of an item return of an item return job.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnIdstringRequired

Body

ReplaceReturnedLineItems

itemReturnJobVersionintegerRequired

Version of the entity to be changed

Example: 1

Responses

200

The returned line items were successfully updated. Updated item return job is returned.

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

400

Invalid input. See response for details.

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

409

A version conflict occurred.

application/json

put/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems

PUT /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 803

{
  "itemReturnJobVersion": 1,
  "returnedLineItems": [
    {
      "itemConditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "customAttributes": {},
      "decisionReason": {
        "reasonLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "comment": "Upper corner damaged"
      },
      "itemConditionComment": "Upper corner damaged",
      "itemReturnJobLineItemRef": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
      "reasons": [
        {
          "reasonLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "comment": "Upper corner damaged",
          "reason": "text"
        }
      ],
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "scannedCodes": [
        "text"
      ],
      "status": "OPEN",
      "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
    }
  ]
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

List item returns

get

Returns the item returns for a given item return job.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

Responses

200

Get all item returns for a given item return job

application/json

ItemReturn

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

parcelRefsstring[] · max: 50Optional

references the parcel

Example: 672f3f72-b5d3-47c7-941c-9af5348e3cd7

returnFacilityRefstringRequired

scannableCodesstring[] · max: 50Optional

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptionalDeprecated

deprecated: will be automatically deducted from related itemReturnJob

Example: MY_ORDER_ID

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

get/api/itemreturnjobs/{itemReturnJobId}/itemreturns

GET /api/itemreturnjobs/{itemReturnJobId}/itemreturns HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "created": "2020-02-03T08:45:51.525Z",
    "customAttributes": {},
    "id": "text",
    "lastModified": "2020-02-03T09:45:51.525Z",
    "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
    "returnedLineItems": [
      {
        "itemConditionLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "customAttributes": {},
        "decisionReason": {
          "reasonLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "comment": "Upper corner damaged",
          "reason": "text"
        },
        "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
        "itemCondition": "Damaged",
        "itemConditionComment": "Upper corner damaged",
        "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
        "reasons": [
          {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          }
        ],
        "recordableAttributes": [
          {
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "group": "general",
            "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
            "key": "country of origin",
            "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
            "recordingRule": "MANDATORY",
            "value": "Germany"
          }
        ],
        "refund": {
          "percent": 80.6,
          "price": {
            "currency": "EUR",
            "value": 20.55
          },
          "status": "OPEN"
        },
        "scannedCodes": [
          "text"
        ],
        "status": "OPEN",
        "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
      }
    ],
    "returnFacilityRef": "text",
    "scannableCodes": [
      "text"
    ],
    "status": "ANNOUNCED"
  }
]

Get item return job

get

Returns an item return job with the provided id.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

Responses

200

Returns Item Return Job with the provided id

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

get/api/itemreturnjobs/{itemReturnJobId}

GET /api/itemreturnjobs/{itemReturnJobId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Get item returns

get

Returns the item returns matching the given parameters.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

searchTermstringOptional

Search term you want to get the corresponding item returns. Search will be performed on multiple fields, including return id, tenant order id, customer name, tenant article ids, artile titles

itemReturnStatusstring[]Optional

ItemReturnStatus of an included ItemReturn to filter the results

itemReturnLineItemStatusstring[]Optional

ItemReturnLineItemStatus of an included itemReturnLineItem to filter the results

sizeintegerOptional

number of entities to show

startAfterIdstringOptional

entity to start after

orderBystringOptional

sorting for the results

anonymizedbooleanOptional

show anonymized entities or not

facilityRefsstring[]Optional

facilities to filter the results

Responses

200

All Item Returns matching the given parameters

application/json

ItemReturns

totalCountnumberRequired

Total number of found entities for this query

Example: 42

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

get/api/itemreturns

GET /api/itemreturns HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "searchPaths": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "totalCount": 42
}

Update returned line item

patch

Patch for a ItemReturn LineItem. This is used to update the returned line item.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnIdstringRequired

returnedLineItemIdstringRequired

id of the returnedLineItem

Body

ItemReturnLineItemForUpdate

itemReturnJobVersionintegerRequired

version of the overlaying itemReturnJob

Example: 42

statusstring · enumOptionalPossible values:

Responses

200

Updated ItemReturnJob

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

400

Invalid input. See response for details.

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

patch/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems/{returnedLineItemId}

PATCH /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems/{returnedLineItemId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 256

{
  "decisionReason": {
    "reasonLocalized": {
      "de_DE": "Wert",
      "en_US": "Value",
      "ru_RU": "значение"
    },
    "comment": "Upper corner damaged"
  },
  "itemReturnJobVersion": 42,
  "refund": {
    "percent": 80.6,
    "price": {
      "currency": "EUR",
      "value": 20.55
    },
    "status": "OPEN"
  },
  "status": "OPEN"
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Create item return

post

Create a new item return for an item return job

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

Body

AddItemReturnToItemReturnJob

itemReturnJobVersionintegerRequired

Version of the itemReturnJob the itemReturn gets added to

Example: 1

Responses

200

ItemReturnJob containing the newly created item return

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

post/api/itemreturnjobs/{itemReturnJobId}/itemreturns

POST /api/itemreturnjobs/{itemReturnJobId}/itemreturns HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 903

{
  "itemReturnForCreation": {
    "returnedLineItems": [
      {
        "itemConditionLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "customAttributes": {},
        "decisionReason": {
          "reasonLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "comment": "Upper corner damaged"
        },
        "itemConditionComment": "Upper corner damaged",
        "itemReturnJobLineItemRef": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
        "reasons": [
          {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          }
        ],
        "recordableAttributes": [
          {
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "group": "general",
            "recordingRule": "MANDATORY",
            "value": "Germany"
          }
        ],
        "scannedCodes": [
          "text"
        ],
        "status": "OPEN",
        "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
      }
    ],
    "returnFacilityRef": "text",
    "scannableCodes": [
      "text"
    ],
    "status": "ANNOUNCED"
  },
  "itemReturnJobVersion": 1
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Deprecated

Delete item return

delete

This part of the API is deprecated. For details, see the API release lifecycle documentation. Delete an item return from an item return job

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnIdstringRequired

id of the item return you want to delete

Query parameters

itemReturnJobVersionnumberRequired

version of the item return job to delete the item return for

Responses

200

item return was found and successfully deleted. Updated item return job is returned.

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

delete/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}

DELETE /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}?itemReturnJobVersion=1 HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Get pack job return note

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

packJobIdstringRequired

ID of the PackJob

Query parameters

localestringOptional

Provide the localized values for the delivery note. If not provided the default locale is used. For example de_DE.

Responses

200

Returns a return note for the packjob.

application/pdf

401

Your user is not allowed to operate against this API instance

application/pdf

403

Your user, although recognized, is not authorized to use this endpoint

application/pdf

404

Entity not found

application/pdf

get/api/packjobs/{packJobId}/returnnote

GET /api/packjobs/{packJobId}/returnnote HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Get pick job return note

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pickjobIdstringRequired

ID of the Pickjob

Responses

200

Returns a return note for the pickjob.

application/pdf

401

Your user is not allowed to operate against this API instance

application/pdf

403

Your user, although recognized, is not authorized to use this endpoint

application/pdf

404

Entity not found

application/pdf

get/api/pickjobs/{pickjobId}/returnnote

GET /api/pickjobs/{pickjobId}/returnnote HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Create item return job

post

Creates a new item return job.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

ItemReturnJobForCreation

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringOptional

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

Responses

200

Created entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

post/api/itemreturnjobs

POST /api/itemreturnjobs HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2295

{
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "customAttributes": {},
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text"
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Create item return parcel

post

This part of the API is in Beta status. For details, see the API release lifecycle documentation. Returns all parcels for an itemReturn.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

itemReturnJobId

itemReturnIdstringRequired

id of the itemReturn to create a parcel for

Body

ParcelForCreation

carrierProductstringOptional

Desired product of given carrier to choose when ordering a label

Example: EXPRESS

carrierRefstringOptional

references the carrier to be used for sending. Can not be set when creating a parcel for an existing shipment.

customAttributesobjectOptional

Attributes that can be added to the parcel. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

customProductValuenumberOptional

Set this value if you want to overwrite the calculated product value of the parcel.

Example: 12.5

loadUnitRefsstring[]Optional

Reference to array of load unit Refs

parentRefstringOptional

Reference to the parent container of this parcel

productValuenumberOptional

Monetary value of all goods in this parcel. Needed for sending cross border packages (customs) To be interpreted as money in the currency given under paymentInformation.currency. This value is calculated from the items in the parcel.

Example: 12.5

productValueTypestring · enumOptional

ProductValueType

Example: INSURANCEPossible values:

shortIdstringOptionalExample: AA12-1

statusstring · enumOptional

ParcelStatus

Possible values:

tenantOrderIdstringOptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546

tenantParcelIdstringOptional

Tenant specific parcel id, needs to be unique for non obsolete or canceled parcel

Example: MY-PARCEL-12345

Responses

201

Create a parcel for an itemReturn

application/json

BaseOperationalContainer

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

sequenceNumberinteger · int32 · max: 10000Optional

Incremental number to distinguish containers of the same type. Virtual container's sequenceNumber is always 0, non virtual containers are always greater than 0.

Example: 100

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

carrierProductstringOptional

Desired product of given carrier to choose when ordering a label

Example: EXPRESS

carrierRefstringRequired

Reference to the carrier this parcel should be send by

Example: cf00e102-34f2-45c1-a846-6a21f384321e

customAttributesobjectOptional

Attributes that can be added to the parcel. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

customProductValuenumberOptional

Set this value if you want to overwrite the calculated product value of the parcel. This field uses the smallest denomination, e.g. Euro Cents. So a value of 1250 represents 12,50€.

Example: 12.5

documentsRefstringOptional

Reference to the documents collection from this entity

facilityRefstringOptional

idstringRequired

The id of this parcel. It is generated during creation automatically and suits as the primary identifier of the described entity.

Example: 95EWrieX09OmeriXIUbb

loadUnitRefsstring[]Required

Reference to array of load unit Refs

operativeProcessRefstringOptional

processRefstringRequired

productValuenumberOptional

Example: 1250

productValueTypestring · enumOptional

ProductValueType

Example: INSURANCEPossible values:

shipmentRefstringOptional

The id of this shipment this parcel has been created for.

Example: 95EWrieX09OmeriXIUbb

shortIdstringOptionalExample: AA12-1

statusstring · enumRequired

ParcelStatus

Possible values:

tenantOrderIdstringOptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546

tenantParcelIdstringOptional

Tenant specific parcel id, needs to be unique for non obsolete or canceled parcel

Example: MY-PARCEL-12345

workflowInformationone ofRequired

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

Entity not found

application/json

post/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/parcels

POST /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/parcels HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 4457

{
  "carrierInformation": {
    "shippingContainerNumber": "123456-ABC"
  },
  "carrierProduct": "EXPRESS",
  "carrierRef": "text",
  "customAttributes": {},
  "customProductValue": 12.5,
  "dimensions": {
    "customWeight": 1,
    "height": 1,
    "length": 1,
    "weight": 1,
    "width": 1
  },
  "invoice": {
    "addressType": "POSTAL_ADDRESS",
    "companyName": "Speedy Boxales Ltd.",
    "coordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "email": "test@try.de",
    "firstName": "Maxine",
    "lastName": "Muller",
    "personalTitle": "Dr.",
    "salutation": "Frau",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr."
  },
  "items": [
    {
      "article": {},
      "customAttributes": {},
      "globalLineItemId": "text",
      "measurementUnitKey": "pcs",
      "quantity": 1,
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "scannableCodes": [
        "text"
      ],
      "secondaryMeasurementUnitKey": "g",
      "secondaryQuantity": 42
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "parentRef": "text",
  "paymentInformation": {
    "currency": "EUR"
  },
  "pickUpInformation": {
    "endTime": "2026-07-22T22:58:17.431Z",
    "startTime": "2026-07-22T22:58:17.431Z"
  },
  "productValue": 12.5,
  "productValueCurrency": {
    "currency": "EUR",
    "decimalPlaces": 2
  },
  "productValueType": "INSURANCE",
  "recipient": {
    "addressType": "POSTAL_ADDRESS",
    "companyName": "Speedy Boxales Ltd.",
    "coordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "email": "test@try.de",
    "firstName": "Maxine",
    "lastName": "Muller",
    "personalTitle": "Dr.",
    "salutation": "Frau",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr."
  },
  "result": {
    "carrierParcelRef": "84168117830018",
    "carrierTrackingNumber": "84168117830018",
    "carrierTrackingStatus": "registered",
    "customsDocumentId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "customsDocumentUrl": "someCepProvider.com/pathToReturnLabel.pdf",
    "errors": {
      "labelError": "text",
      "returnLabelError": "text"
    },
    "labelUrl": "%%HOST%%/api/parcels/{parcelId}/labels/84168117830018.pdf",
    "proxyId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "returnLabelId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "returnLabelUrl": "someCepProvider.com/pathToReturnLabel.pdf",
    "returnTrackingUrl": "http://track.io/3a186c51d4",
    "sendLabelUrl": "someCepProvider.com/pathToSendLabel.pdf",
    "summary": "Package label was successfully requested at DHL.",
    "trackingStatus": "registered",
    "trackingUrl": "http://track.io/3a186c51d4"
  },
  "returnAddress": {
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr.",
    "companyName": "Speedy Boxales Ltd.",
    "emailAddresses": [
      {
        "recipient": "'Mailinglist reaching all the employees', 'Marc Fulton, Manager', etc.",
        "value": "text"
      }
    ],
    "resolvedCoordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "resolvedTimeZone": {
      "offsetInSeconds": 28800,
      "source": "Google Maps API",
      "timeZoneId": "America/Los_Angeles",
      "timeZoneName": "Pacific Standard Time"
    }
  },
  "sender": {
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr.",
    "companyName": "Speedy Boxales Ltd.",
    "emailAddresses": [
      {
        "recipient": "'Mailinglist reaching all the employees', 'Marc Fulton, Manager', etc.",
        "value": "text"
      }
    ],
    "resolvedCoordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "resolvedTimeZone": {
      "offsetInSeconds": 28800,
      "source": "Google Maps API",
      "timeZoneId": "America/Los_Angeles",
      "timeZoneName": "Pacific Standard Time"
    }
  },
  "services": {
    "additionalTransportInsurance": true,
    "adultSignature": true,
    "bulkyGoods": true,
    "customerSignature": true,
    "handoverToRecipientOnly": true,
    "identityAgeCheck18": true,
    "identityCheckCompany": true,
    "identityCheckPrivate": true,
    "noNeighborDelivery": true,
    "saturdayDelivery": true,
    "signature": true
  },
  "shortId": "AA12-1",
  "status": "OPEN",
  "tenantOrderId": "R456728546",
  "tenantParcelId": "MY-PARCEL-12345",
  "transfers": [
    {
      "id": "018fe899-80ec-70f8-9bda-f7cc904bc0bf",
      "type": "RECEIVER"
    }
  ]
}

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "sequenceNumber": 100,
  "anonymized": false,
  "carrierInformation": {
    "shippingContainerNumber": "123456-ABC"
  },
  "carrierProduct": "EXPRESS",
  "carrierRef": "cf00e102-34f2-45c1-a846-6a21f384321e",
  "customAttributes": {},
  "customProductValue": 12.5,
  "dimensions": {
    "customWeight": 1,
    "height": 1,
    "length": 1,
    "weight": 1,
    "width": 1
  },
  "documentsRef": "text",
  "facilityRef": "text",
  "id": "95EWrieX09OmeriXIUbb",
  "invoice": {
    "addressType": "POSTAL_ADDRESS",
    "companyName": "Speedy Boxales Ltd.",
    "coordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "email": "test@try.de",
    "firstName": "Maxine",
    "lastName": "Muller",
    "personalTitle": "Dr.",
    "salutation": "Frau",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr."
  },
  "items": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "customAttributes": {},
        "imageUrl": "https://example.com/resource",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1,
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ]
      },
      "customAttributes": {},
      "globalLineItemId": "text",
      "id": "ae3ba67c-a42c-4816-96ac-16231e49640c",
      "measurementUnitKey": "pcs",
      "quantity": 5,
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "scannableCodes": [
        "text"
      ],
      "secondaryMeasurementUnitKey": "g",
      "secondaryQuantity": 42,
      "originId": "df671041-10dd-4600-a2ff-e9ffe2556bba"
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "operativeProcessRef": "text",
  "paymentInformation": {
    "currency": "EUR"
  },
  "pickUpInformation": {
    "endTime": "2026-07-22T22:58:17.431Z",
    "startTime": "2026-07-22T22:58:17.431Z"
  },
  "postalCharges": {
    "currency": "EUR",
    "value": 15.5
  },
  "processRef": "text",
  "productValue": 1250,
  "productValueCurrency": {
    "currency": "EUR",
    "decimalPlaces": 2
  },
  "productValueType": "INSURANCE",
  "recipient": {
    "addressType": "POSTAL_ADDRESS",
    "companyName": "Speedy Boxales Ltd.",
    "coordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "email": "test@try.de",
    "firstName": "Maxine",
    "lastName": "Muller",
    "personalTitle": "Dr.",
    "salutation": "Frau",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr."
  },
  "result": {
    "carrierParcelRef": "84168117830018",
    "carrierTrackingNumber": "84168117830018",
    "carrierTrackingStatus": "registered",
    "customsDocumentId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "customsDocumentUrl": "someCepProvider.com/pathToReturnLabel.pdf",
    "errors": {
      "labelError": "text",
      "returnLabelError": "text"
    },
    "labelUrl": "%%HOST%%/api/parcels/{parcelId}/labels/84168117830018.pdf",
    "proxyId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "returnLabelId": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
    "returnLabelUrl": "someCepProvider.com/pathToReturnLabel.pdf",
    "returnTrackingUrl": "http://track.io/3a186c51d4",
    "sendLabelUrl": "someCepProvider.com/pathToSendLabel.pdf",
    "summary": "Package label was successfully requested at DHL.",
    "trackingStatus": "registered",
    "trackingUrl": "http://track.io/3a186c51d4"
  },
  "returnAddress": {
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr.",
    "companyName": "Speedy Boxales Ltd.",
    "emailAddresses": [
      {
        "recipient": "'Mailinglist reaching all the employees', 'Marc Fulton, Manager', etc.",
        "value": "text"
      }
    ],
    "resolvedCoordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "resolvedTimeZone": {
      "offsetInSeconds": 28800,
      "source": "Google Maps API",
      "timeZoneId": "America/Los_Angeles",
      "timeZoneName": "Pacific Standard Time"
    }
  },
  "sender": {
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "province": "NRW",
    "street": "Hauptstr.",
    "companyName": "Speedy Boxales Ltd.",
    "emailAddresses": [
      {
        "recipient": "'Mailinglist reaching all the employees', 'Marc Fulton, Manager', etc.",
        "value": "text"
      }
    ],
    "resolvedCoordinates": {
      "lat": 50.937531,
      "lon": 6.960279
    },
    "resolvedTimeZone": {
      "offsetInSeconds": 28800,
      "source": "Google Maps API",
      "timeZoneId": "America/Los_Angeles",
      "timeZoneName": "Pacific Standard Time"
    }
  },
  "services": {
    "additionalTransportInsurance": true,
    "adultSignature": true,
    "bulkyGoods": true,
    "customerSignature": true,
    "handoverToRecipientOnly": true,
    "identityAgeCheck18": true,
    "identityCheckCompany": true,
    "identityCheckPrivate": true,
    "noNeighborDelivery": true,
    "saturdayDelivery": true,
    "signature": true
  },
  "shipmentRef": "95EWrieX09OmeriXIUbb",
  "shortId": "AA12-1",
  "status": "OPEN",
  "tenantOrderId": "R456728546",
  "tenantParcelId": "MY-PARCEL-12345",
  "transfers": [
    {
      "id": "018fe899-80ec-70f8-9bda-f7cc904bc0bf",
      "type": "RECEIVER"
    }
  ],
  "workflowInformation": {
    "instanceRef": "64c13ab08edf48a008793cac",
    "isAvailable": true,
    "nodeRef": "text"
  }
}

Call item return job action

post

Applies an action to an Item Return Job. Check ItemReturnJobActionsParameters for available actions.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

itemReturnJobIdstringRequired

Body

Responses

200

Updated entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false

createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired

lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]

processRefstringRequired

scannableCodesstring[] · max: 50Optional

shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12

statusstring · enumRequiredPossible values:

tenantOrderIdstringOptional

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

The requested entity was not found

application/json

post/api/itemreturnjobs/{itemReturnJobId}/actions

POST /api/itemreturnjobs/{itemReturnJobId}/actions HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "name": "StartItemReturnJob",
  "version": 1
}

{
  "anonymized": false,
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "province": "NRW",
      "street": "Hauptstr."
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "customAttributes": {},
  "id": "text",
  "itemReturns": [
    {
      "created": "2020-02-03T08:45:51.525Z",
      "customAttributes": {},
      "id": "text",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "parcelRefs": "672f3f72-b5d3-47c7-941c-9af5348e3cd7",
      "returnedLineItems": [
        {
          "itemConditionLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "customAttributes": {},
          "decisionReason": {
            "reasonLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "comment": "Upper corner damaged",
            "reason": "text"
          },
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemConditionComment": "Upper corner damaged",
          "itemReturnJobLineItemRefs": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "reasons": [
            {
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged",
              "reason": "text"
            }
          ],
          "recordableAttributes": [
            {
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "group": "general",
              "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "key": "country of origin",
              "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
              "recordingRule": "MANDATORY",
              "value": "Germany"
            }
          ],
          "refund": {
            "percent": 80.6,
            "price": {
              "currency": "EUR",
              "value": 20.55
            },
            "status": "OPEN"
          },
          "scannedCodes": [
            "text"
          ],
          "status": "OPEN",
          "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb"
        }
      ],
      "returnFacilityRef": "text",
      "scannableCodes": [
        "text"
      ],
      "status": "ANNOUNCED"
    }
  ],
  "lastModified": "2026-06-17T12:00:00.000Z",
  "notReturnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "originFacilityRefs": [
    "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
    "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
  ],
  "processRef": "text",
  "returnableLineItems": [
    {
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ],
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1
      },
      "customAttributes": {},
      "delivered": 7,
      "globalLineItemId": "text",
      "id": "611c860f-3f00-4b01-9f4c-64cdee38a30e",
      "recordableAttributes": [
        {
          "keyLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "group": "general",
          "id": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "key": "country of origin",
          "originId": "17ebfdfb-e1b4-4913-9962-3aef2b49f16f",
          "recordingRule": "MANDATORY",
          "value": "Germany"
        }
      ],
      "returnable": 7,
      "returned": 5,
      "scannableCodes": [
        "text"
      ],
      "serviceJobRefs": [
        "0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f",
        "0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"
      ]
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "status": "OPEN",
  "tenantOrderId": "text",
  "version": 1
}

Upsert return configuration

put

Updates the return configuration for the tenant. If no configuration exists, it will be created.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

ReturnConfiguration

activebooleanRequiredDeprecated

Enable or disable legacy returns. Use returnTypeConfiguration instead

Default: trueExample: true

allowTriggerRefundbooleanOptional

If true, a refund can be triggered. If false, the endpoints to trigger a refund are disabled.

Default: false

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

Responses

200

ItemReturnJob containing the newly created item return

application/json

LocalizedReturnConfiguration

activebooleanRequiredDeprecated

Enable or disable legacy returns. Use returnTypeConfiguration instead

Default: trueExample: true

allowTriggerRefundbooleanOptional

If true, a refund can be triggered. If false, the endpoints to trigger a refund are disabled.

Default: false

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2026-06-17T12:00:00.000Z

versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1

201

ItemReturnJob containing the newly created item return

application/json

400

Invalid input. See response for details.

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

409

A version conflict occurred.

application/json

put/api/configurations/return

PUT /api/configurations/return HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 605

{
  "allowTriggerRefund": false,
  "availableDecisionReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "context": [
        {
          "type": "ITEM_RETURN_LINE_ITEM_STATUS",
          "values": [
            "ACCEPTED"
          ]
        }
      ],
      "reason": "Item damaged"
    }
  ],
  "availableItemConditions": [
    {
      "conditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      }
    }
  ],
  "availableReturnReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "identifier": "A"
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "lastModified": "2026-06-17T12:00:00.000Z",
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "version": 1
}

{
  "allowTriggerRefund": false,
  "availableDecisionReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "context": [
        {
          "type": "ITEM_RETURN_LINE_ITEM_STATUS",
          "values": [
            "ACCEPTED"
          ]
        }
      ],
      "reason": "Item damaged"
    }
  ],
  "availableItemConditions": [
    {
      "conditionLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "condition": "Damaged"
    }
  ],
  "availableReturnReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "identifier": "A",
      "reason": "Damaged"
    }
  ],
  "created": "2026-06-17T12:00:00.000Z",
  "lastModified": "2026-06-17T12:00:00.000Z",
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "version": 1
}

Get parcel return note

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

parcelIdstringRequired

ID of parcel you want to retrieve returnNote for

Query parameters

localestringOptional

Provide the localized values for the returnNote. If not provided the default locale is used. For example de_DE.

Responses

200

Get delivery note as pdf.

application/pdf

ReturnNote

qrCodeContentstringOptional

401

Your user is not allowed to operate against this API instance

application/pdf

403

Your user, although recognized, is not authorized to use this endpoint

application/pdf

404

Parcel not found

application/pdf

get/api/parcels/{parcelId}/returnnote

GET /api/parcels/{parcelId}/returnnote HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "companyAddress": {
    "city": "Langenfeld",
    "country": "Germany",
    "houseNumber": "42a",
    "name": "OC fulfillment GmbH",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddress": {
    "city": "Langenfeld",
    "companyName": "OC Fulfillment GmbH",
    "firstName": "Maxine",
    "houseNumber": "42a",
    "lastName": "Muller",
    "personalTitle": "Prof.",
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "deliveryAddresses": [
    {
      "city": "Langenfeld",
      "companyName": "OC Fulfillment GmbH",
      "firstName": "Maxine",
      "houseNumber": "42a",
      "lastName": "Muller",
      "personalTitle": "Prof.",
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "items": [
    {
      "id": "text",
      "quantity": 1,
      "substitutes": "text",
      "title": "text"
    }
  ],
  "orderInformation": {
    "orderDate": "2020-02-03T08:45:50.525Z",
    "orderNumber": "R456728546"
  },
  "qrCodeContent": "text"
}

Last updated 6 months ago