Returns 2.0

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

A return signifies our process where a customer sends a purchased product back, seeking a refund, exchange, or store credit. This occurs when a customer is dissatisfied, changes their mind, or encounters issues like defects, incorrect sizing, or incompatibility. The return process typically involves the customer physically bringing the item to our store or initiating an online return.

Upon receiving the returned item, we enable the assessment of the item's condition, check eligibility based on our return policy, and then provide a suitable resolution—be it a refund or store credit. This requires us to have the capability to manually create the return.

The specifics of our return policy, including time limits, condition requirements, and refund methods, may vary.

ItemReturnJob

An ItemReturnJob serves as a container for all potential ItemReturns associated with a placed Order. It encompasses all items eligible for return and tracks actual returned ItemReturns, including the returned items within them.

During interactions with the ItemReturnJob, validations ensure that only items purchased in the given Order can be returned, and only in the quantities available.

For user convenience, the ItemReturnJob presents the available returnable items along with a summary of returned items in a single easily readable line item.

Example:

{
   returnableLineItems: [
      {
        delivered: 5,
        returned: 3,
        returnable: 2,
        ...
      }
   ],
  ...
}

The values for returned and returnable are dynamically calculated, considering the included ItemReturns.

An ItemReturnJob is automatically generated through the designated Workflow after the Handover process. If the Handover Feature isn't utilized, the ItemReturnJob can be created via API methods.

Creates a new ItemReturnJob

post

Body

processRefstringoptional

originFacilityRefsstring[]required

statusstring · enumrequired

Options: OPEN, IN_PROGRESS, FINISHED, CANCELED

tenantOrderIdstringoptional

consumerAddressesall of[]required

scannableCodesstring[]optional

shortIdstringoptional

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

Example: AS12

returnableLineItemsobject[] · min: 1required

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/itemreturnjobs' \
  --header 'Content-Type: application/json' \
  --data '{
    "processRef": "text",
    "originFacilityRefs": [
      "text"
    ],
    "status": "OPEN",
    "tenantOrderId": "text",
    "consumerAddresses": [
      {
        "additionalAddressInfo": "to care of: Mrs. Müller",
        "city": "Langenfeld",
        "country": "DE",
        "province": "NRW",
        "customAttributes": {},
        "houseNumber": "42a",
        "phoneNumbers": [
          {
            "customAttributes": {},
            "label": "text",
            "type": "MOBILE",
            "value": "text"
          }
        ],
        "postalCode": "40764",
        "street": "Hauptstr."
      }
    ],
    "scannableCodes": [
      "text"
    ],
    "shortId": "AS12",
    "returnableLineItems": []
  }'

application/json

200

401

403

200

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ],
        "prices": [
          {
            "pricePerUnit": 9.99,
            "currency": "EUR"
          }
        ]
      },
      "delivered": 1,
      "notReturnableItemsExists": true,
      "scannableCodes": [
        "text"
      ],
      "customAttributes": {}
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "customAttributes": {},
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Created entity

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

All created ItemReturnJobs are accessible through this API call, with various filtering parameters available for refinement.

Get all Item Return Jobs

get

Query parameters

facilityIdstringoptional

facility to filter the results

itemReturnJobScannableCodesstring[]optional

scannableCodes of the item return job to filter the results

itemReturnScannableCodesstring[]optional

scannableCodes of the item return to filter the results

itemReturnJobStatusstring[]optional

ItemReturnJobStatus to filter the results

itemReturnStatusstring[]optional

ItemReturnStatus of an included ItemReturn to filter the results

searchTermstringoptional

Term by which to search through the fields

startAfterIdstringoptional

entity to start after

sizeinteger · default: 25optional

number of entities to show

anonymizedboolean · default: falseoptional

show anonymized entities or not

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/itemreturnjobs'

200

401

403

200

[
  {
    "created": "2020-02-03T08:45:51.525Z",
    "lastModified": "2020-02-03T09:45:51.525Z",
    "version": 42
  }
]

All Item Return Jobs matching the given parameters

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

Alternatively, you can retrieve details of a specific ItemReturnJob via this API call.

Get Item Return Job by id

get

Path parameters

itemReturnJobIdstringrequired

id of the item return job

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/itemreturnjobs/{itemReturnJobId}'

200

401

403

404

200

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ],
        "prices": [
          {
            "pricePerUnit": 9.99,
            "currency": "EUR"
          }
        ]
      },
      "delivered": 1,
      "notReturnableItemsExists": true,
      "scannableCodes": [
        "text"
      ],
      "customAttributes": {}
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "customAttributes": {},
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Returns Item Return Job with the provided id

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

To update the Status of an ItemReturnJob, utilize the ItemReturnJobStatusChangeAction API Action:

Updates a new ItemReturnJob

post

Path parameters

itemReturnJobIdstringrequired

id of the Item Return Job

Body

any ofoptional

Action to start a ItemReturnJob.

Action to finish a ItemReturnJob.

Action to restart a ItemReturnJob.

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/itemreturnjobs/{itemReturnJobId}/actions' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "StartItemReturnJob",
    "version": 1
  }'

application/json

200

401

403

404

200

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ],
        "prices": [
          {
            "pricePerUnit": 9.99,
            "currency": "EUR"
          }
        ]
      },
      "delivered": 1,
      "notReturnableItemsExists": true,
      "scannableCodes": [
        "text"
      ],
      "customAttributes": {}
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "customAttributes": {},
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Updated entity

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

Once an ItemReturnJob is established, ItemReturns can be appended.

ItemReturn

An ItemReturn represents all items actually returned within the associated ItemReturnJob. It's imperative to have a valid ItemReturnJob before creating an ItemReturn.

While adding or updating an ItemReturn within an existing ItemReturnJob, item validations ensure that the returned quantity doesn't exceed the delivered and previously returned amounts.

To initiate the creation of a new ItemReturn, utilize the AddItemReturnAction API Action:

Updates a new ItemReturnJob

post

Path parameters

itemReturnJobIdstringrequired

id of the Item Return Job

Body

any ofoptional

Action to start a ItemReturnJob.

Action to finish a ItemReturnJob.

Action to restart a ItemReturnJob.

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/itemreturnjobs/{itemReturnJobId}/actions' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "StartItemReturnJob",
    "version": 1
  }'

application/json

200

401

403

404

200

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ],
        "prices": [
          {
            "pricePerUnit": 9.99,
            "currency": "EUR"
          }
        ]
      },
      "delivered": 1,
      "notReturnableItemsExists": true,
      "scannableCodes": [
        "text"
      ],
      "customAttributes": {}
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "customAttributes": {},
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Updated entity

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

For updating an existing ItemReturn, utilize the following API Actions:

Actions for a ItemReturn

post

Path parameters

itemReturnJobIdstringrequired

id of the Item Return Job

itemReturnIdstringrequired

id of the Item Return

Body

any ofoptional

Action to announce an ItemReturn.

Action to open an ItemReturn.

Action to start an ItemReturn.

Action to pause an ItemReturn.

Action to finish an ItemReturn.

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "AnnounceItemReturn",
    "itemReturnJobVersion": 1
  }'

application/json

200

401

403

404

200

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ],
        "prices": [
          {
            "pricePerUnit": 9.99,
            "currency": "EUR"
          }
        ]
      },
      "delivered": 1,
      "notReturnableItemsExists": true,
      "scannableCodes": [
        "text"
      ],
      "customAttributes": {}
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "customAttributes": {},
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Updated entity

https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml

• Change the Status via ItemReturnStatusChange

• Replace items via ItemReturnReplaceReturnedLineItemsAction

• Remove the ItemReturn from the ItemReturnJob using DeleteItemReturnAction