Return reasons

Return reasons should help our customers to specify why certain items have been returned by the customer while creating an ItemReturn. In order to get pre-defined return reasons, these reasons can be added to the given ReturnConfiguration (1)

These reasons can be passed while creating an ItemReturn through the API. Having default reasons is optional and not mandatory for passing reasons into an ItemReturn. (2)

Default values for return reasons in the backend are not provided; however, it is possible to manage them on the client side. Like we are doing it with our app by setting the default value for return reason to "no reason". If no additional reasons are specified through the backend, the return reasons will not be displayed.

Adding predefined item conditions

You can add translatable availableReturnReasons to the returnConfiguration via API. The translation depends on the locale of the user using this endpoint and the tenantLocaleConfiguration as a fallback.

Get the current configuration for returns

GET/api/configurations/return

Response

200401403404

Return config found.

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/configurations/return', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "returnTypeConfiguration": {
    "type": "RETURN"
  }
}

Change the tenant wide return configuration

PUT/api/configurations/return

Body

application/json

Desired return configuration to create/update

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.

Response

200201400401403409

The return configuration was successfully updated.

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/configurations/return', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "active": true
    }),
});
const data = await response.json();

Response

{
  "returnTypeConfiguration": {
    "type": "RETURN"
  }
}

Using return reasons in ItemReturns

A user of our api can use this predefined return reasons or provide their own ones when creating or updating ItemReturnLineItem of an ItemReturn. The translatable return reason can be provided like this example:

localizedReason = { de_DE: 'Falsche Farbe', en_US: 'Wrong color' }

When getting this ItemReturn via REST oder GQL, you will receive an additional field called reason which contains only the translated value. This translation depends on the users locale.

Getting and setting this values via REST:\

Provides metadata for currently available artifacts for a platform

GEThttps://%%HOST%%//api/artifacts/{platform}

Authorization

firebase

Path parameters

platform*enum

Platform for which to list artifacts

android

Response

200400401403

All available artifacts for the selected platform

Body

application/json

artifacts*array of ArtifactMetadataItem (object)

platform*string

Platform name for which the artifact list is generated

Request

JavaScriptCurl

const response = await fetch('https://%%HOST%%//api/artifacts/{platform}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "artifacts": [
    {
      "buildDate": "2020-02-03T08:45:50.525Z",
      "download": {
        "expiration": "2020-02-03T08:45:50.525Z",
        "url": "text"
      },
      "versionCode": 42,
      "versionName": "1.0.42"
    }
  ],
  "platform": "android"
}

Get item returns

GEThttps://%%HOST%%//api/itemreturnjobs/{itemReturnJobId}/itemreturns

Authorization

firebase

Path parameters

itemReturnJobId*string

item return job to read the item return for

Query parameters

Response

200401403404

Get all item returns for a given item return job

Body

application/json

any

Request

JavaScriptCurl

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

Get item return by id

GEThttps://%%HOST%%//api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}

Authorization

firebase

Path parameters

itemReturnJobId*string

item return job to read the item return for

itemReturnId*string

id of the item return you want to read

Query parameters

Response

200401403404

Get a specific item return

Body

application/json

id*string

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.

returnFacilityRef*string

status*ItemReturnStatus (enum)

ANNOUNCEDOPENIN_PROGRESSPAUSEDFINISHED

tenantOrderIdstring

scannableCodesarray of string

returnedLineItems*array of ItemReturnLineItem (object)

Request

JavaScriptCurl

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

Response

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

Actions for a ItemReturn

POSThttps://%%HOST%%//api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions

Authorization

firebase

Path parameters

itemReturnJobId*string

id of the Item Return Job

itemReturnId*string

id of the Item Return

Body

application/json

ItemReturnActionsParameter (any of)

ItemReturnStatusChangeActionParameter (object)ItemReturnReplaceReturnedLineItemsActionParameter (object)DeleteItemReturnActionParameter (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('https://%%HOST%%//api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "STATUS_CHANGE",
      "status": "ANNOUNCED"
    }),
});
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"
    }
  ],
  "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"
          ]
        }
      ]
    }
  ],
  "anonymized": false
}