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

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation.Returns the current return configuration for the tenant.

Authorizations
Responses
200

Return config found.

application/json
get
GET /api/configurations/return HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer JWT
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

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation.Updates the return configuration for the tenant. If no configuration exists, it will be created.

Authorizations
Body

ReturnConfiguration

activebooleanRequiredDeprecated

This part of the API is deprecated. For details please check the api-release-life-cycle documentation.Enable or disable legacy returns. Use returnTypeConfiguration instead

Default: true
availableItemConditionsanyOptional

AvailableItemCondition

availableReturnReasonsanyOptional

AvailableReturnReason

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: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer JWT
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?