Return Reasons

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

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 return reasons

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
Responses
200
Return config found.
application/json
get
GET /api/configurations/return HTTP/1.1
Host: 
Accept: */*

{
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "availableItemConditions": [],
  "availableReturnReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Beschädigt",
        "en_US": "Damaged"
      },
      "identifier": "A"
    }
  ],
  "allowTriggerRefund": false,
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Change the tenant wide return configuration

put
Body
activebooleanRequiredDeprecatedDefault: true
availableItemConditionsanyOptional
availableReturnReasonsanyOptional
allowTriggerRefundbooleanOptional

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

Default: false
Responses
200
The return configuration was successfully updated.
application/json
put
PUT /api/configurations/return HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 221

{
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "availableItemConditions": [],
  "availableReturnReasons": [],
  "allowTriggerRefund": false,
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}
{
  "returnTypeConfiguration": {
    "type": "RETURN"
  },
  "availableItemConditions": [],
  "availableReturnReasons": [
    {
      "reasonLocalized": {
        "de_DE": "Beschädigt",
        "en_US": "Damaged"
      },
      "identifier": "A"
    }
  ],
  "allowTriggerRefund": false,
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

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 the ItemReturnLineItem of an ItemReturn. The localized 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 localized value. This translation depends on the users locale.

Getting and setting these values via REST:

Provides metadata for currently available artifacts for a platform

get
Authorizations
Path parameters
platformstring · enumRequired

Platform for which to list artifacts

Possible values:
Responses
200
All available artifacts for the selected platform
application/json
get
GET / HTTP/1.1
Host: %%HOST%%
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

get
Authorizations
Path parameters
itemReturnJobIdstringRequired

item return job to read the item return for

Query parameters
startAfterIdstringOptional

entity to start after

sizeintegerOptional

number of entities to show

Default: 25
Responses
200
Get all item returns for a given item return job
application/json
Responseany
get
GET / HTTP/1.1
Host: %%HOST%%
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[]

Get item return by id

get
Authorizations
Path parameters
itemReturnJobIdstringRequired

item return job to read the item return for

itemReturnIdstringRequired

id of the item return you want to read

Query parameters
startAfterIdstringOptional

entity to start after

sizeintegerOptional

number of entities to show

Default: 25
Responses
200
Get a specific item return
application/json
get
GET / HTTP/1.1
Host: %%HOST%%
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "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": [
    {
      "itemConditionLocalized": {
        "de_DE": "Bschädigt",
        "en_US": "Damaged"
      },
      "itemConditionComment": "Upper corner damaged",
      "tenantArticleId": "a69006ba-7100-4b4d-a610-1ca28016a4eb",
      "scannedCodes": [
        "text"
      ],
      "status": "OPEN",
      "reasons": []
    }
  ]
}

Actions for a ItemReturn

post
Authorizations
Path parameters
itemReturnJobIdstringRequired

id of the Item Return Job

itemReturnIdstringRequired

id of the Item Return

Body
any ofOptional
or
or
Responses
200
Updated entity
application/json
post
POST / HTTP/1.1
Host: %%HOST%%
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "name": "STATUS_CHANGE",
  "itemReturnJobVersion": 1,
  "status": "ANNOUNCED"
}
{
  "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",
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ]
      },
      "delivered": 1,
      "scannableCodes": [
        "text"
      ]
    }
  ],
  "itemReturns": [],
  "anonymized": false,
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}
PreviousReturns 2.0NextItem Conditions

Last updated

Was this helpful?