Returns 2.0

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/api/itemreturnjobs

Body

application/json

processRefstring

originFacilityRefs*array of string

status*ItemReturnJobStatus (enum)

OPENIN_PROGRESSFINISHED

tenantOrderIdstring

consumerAddresses*array of ConsumerAddress (object)

scannableCodesarray of string

shortIdstring

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

returnableLineItems*array of ItemReturnJobLineItemForCreation (object)

Response

200401403

Created entity

Body

application/json

createdstring (date-time)

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

lastModifiedstring (date-time)

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

version*integer (int64)

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

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "originFacilityRefs": [
        "text"
      ],
      "status": "OPEN",
      "consumerAddresses": [
        {}
      ],
      "returnableLineItems": [
        {
          "article": {
            "title": "Cologne Water",
            "tenantArticleId": "4711"
          },
          "delivered": 0
        }
      ]
    }),
});
const data = await response.json();

Response

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.937531,
        "lon": 6.960279
      }
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "id": "text",
      "returned": 0,
      "returnable": 0
    }
  ],
  "itemReturns": [
    {
      "id": "text",
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "returnFacilityRef": "text",
      "status": "ANNOUNCED",
      "tenantOrderId": "text",
      "scannableCodes": [
        "text"
      ],
      "returnedLineItems": [
        {
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemReturnJobLineItemRefs": [
            "a69006ba-7100-4b4d-a610-1ca28016a4eb"
          ],
          "reasons": [
            {
              "reason": "text",
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged"
            }
          ]
        }
      ]
    }
  ],
  "anonymized": false
}

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/api/itemreturnjobs

Query parameters

Response

200401403

All Item Return Jobs matching the given parameters

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

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/api/itemreturnjobs/{itemReturnJobId}

Path parameters

itemReturnJobId*string

id of the item return job

Response

200401403404

Returns Item Return Job with the provided id

Body

application/json

createdstring (date-time)

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

lastModifiedstring (date-time)

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

version*integer (int64)

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

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs/{itemReturnJobId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.937531,
        "lon": 6.960279
      }
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "id": "text",
      "returned": 0,
      "returnable": 0
    }
  ],
  "itemReturns": [
    {
      "id": "text",
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "returnFacilityRef": "text",
      "status": "ANNOUNCED",
      "tenantOrderId": "text",
      "scannableCodes": [
        "text"
      ],
      "returnedLineItems": [
        {
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemReturnJobLineItemRefs": [
            "a69006ba-7100-4b4d-a610-1ca28016a4eb"
          ],
          "reasons": [
            {
              "reason": "text",
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged"
            }
          ]
        }
      ]
    }
  ],
  "anonymized": false
}

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/api/itemreturnjobs/{itemReturnJobId}/actions

Path parameters

itemReturnJobId*string

id of the Item Return Job

Body

application/json

ItemReturnJobActionsParameter (any of)

StartItemReturnJobActionParameter (object)FinishItemReturnJobActionParameter (object)RestartItemReturnJobActionParameter (object)

Response

200401403404

Updated entity

Body

application/json

createdstring (date-time)

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

lastModifiedstring (date-time)

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

version*integer (int64)

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

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs/{itemReturnJobId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "StartItemReturnJob"
    }),
});
const data = await response.json();

Response

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.937531,
        "lon": 6.960279
      }
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "id": "text",
      "returned": 0,
      "returnable": 0
    }
  ],
  "itemReturns": [
    {
      "id": "text",
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "returnFacilityRef": "text",
      "status": "ANNOUNCED",
      "tenantOrderId": "text",
      "scannableCodes": [
        "text"
      ],
      "returnedLineItems": [
        {
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemReturnJobLineItemRefs": [
            "a69006ba-7100-4b4d-a610-1ca28016a4eb"
          ],
          "reasons": [
            {
              "reason": "text",
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged"
            }
          ]
        }
      ]
    }
  ],
  "anonymized": false
}

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/api/itemreturnjobs/{itemReturnJobId}/actions

Path parameters

itemReturnJobId*string

id of the Item Return Job

Body

application/json

ItemReturnJobActionsParameter (any of)

StartItemReturnJobActionParameter (object)FinishItemReturnJobActionParameter (object)RestartItemReturnJobActionParameter (object)

Response

200401403404

Updated entity

Body

application/json

createdstring (date-time)

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

lastModifiedstring (date-time)

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

version*integer (int64)

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

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs/{itemReturnJobId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "StartItemReturnJob"
    }),
});
const data = await response.json();

Response

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.937531,
        "lon": 6.960279
      }
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "id": "text",
      "returned": 0,
      "returnable": 0
    }
  ],
  "itemReturns": [
    {
      "id": "text",
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "returnFacilityRef": "text",
      "status": "ANNOUNCED",
      "tenantOrderId": "text",
      "scannableCodes": [
        "text"
      ],
      "returnedLineItems": [
        {
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemReturnJobLineItemRefs": [
            "a69006ba-7100-4b4d-a610-1ca28016a4eb"
          ],
          "reasons": [
            {
              "reason": "text",
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged"
            }
          ]
        }
      ]
    }
  ],
  "anonymized": false
}

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/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions

Path parameters

itemReturnJobId*string

id of the Item Return Job

itemReturnId*string

id of the Item Return

Body

application/json

ItemReturnActionsParameter (any of)

AnnounceItemReturnActionParameter (object)OpenItemReturnActionParameter (object)StartItemReturnActionParameter (object)PauseItemReturnActionParameter (object)FinishItemReturnActionParameter (object)

Response

200401403404

Updated entity

Body

application/json

createdstring (date-time)

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

lastModifiedstring (date-time)

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

version*integer (int64)

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

Request

JavaScriptCurl

const response = await fetch('/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "AnnounceItemReturn"
    }),
});
const data = await response.json();

Response

{
  "id": "text",
  "processRef": "text",
  "originFacilityRefs": [
    "text"
  ],
  "status": "OPEN",
  "tenantOrderId": "text",
  "consumerAddresses": [
    {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "coordinates": {
        "lat": 50.937531,
        "lon": 6.960279
      }
    }
  ],
  "scannableCodes": [
    "text"
  ],
  "shortId": "AS12",
  "returnableLineItems": [
    {
      "id": "text",
      "returned": 0,
      "returnable": 0
    }
  ],
  "itemReturns": [
    {
      "id": "text",
      "created": "2020-02-03T08:45:51.525Z",
      "lastModified": "2020-02-03T09:45:51.525Z",
      "returnFacilityRef": "text",
      "status": "ANNOUNCED",
      "tenantOrderId": "text",
      "scannableCodes": [
        "text"
      ],
      "returnedLineItems": [
        {
          "id": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
          "itemCondition": "Damaged",
          "itemReturnJobLineItemRefs": [
            "a69006ba-7100-4b4d-a610-1ca28016a4eb"
          ],
          "reasons": [
            {
              "reason": "text",
              "reasonLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "comment": "Upper corner damaged"
            }
          ]
        }
      ]
    }
  ],
  "anonymized": false
}

[https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/api.swagger.yaml](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