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.
A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.
AS12
Attributes that can be added to the entity. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.
POST /api/itemreturnjobs HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 506
{
"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": [],
"notReturnableLineItems": [],
"customAttributes": {}
}
{
"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",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"notReturnableLineItems": [
{
"article": {
"customAttributes": {},
"imageUrl": "text",
"tenantArticleId": "4711",
"title": "Cologne Water",
"titleLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"weight": 1,
"attributes": [
{
"category": "descriptive",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"itemReturns": [],
"anonymized": false,
"customAttributes": {},
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
All created ItemReturnJobs
are accessible through this API call, with various filtering parameters available for refinement.
facility to filter the results
scannableCodes of the item return job to filter the results
scannableCodes of the item return to filter the results
ItemReturnJobStatus to filter the results
ItemReturnStatus of an included ItemReturn to filter the results
Term by which to search through the fields
entity to start after
number of entities to show
25
show anonymized entities or not
false
GET /api/itemreturnjobs HTTP/1.1
Host:
Accept: */*
[
{
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
]
Alternatively, you can retrieve details of a specific ItemReturnJob
via this API call.
id of the item return job
GET /api/itemreturnjobs/{itemReturnJobId} HTTP/1.1
Host:
Accept: */*
{
"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",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"notReturnableLineItems": [
{
"article": {
"customAttributes": {},
"imageUrl": "text",
"tenantArticleId": "4711",
"title": "Cologne Water",
"titleLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"weight": 1,
"attributes": [
{
"category": "descriptive",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"itemReturns": [],
"anonymized": false,
"customAttributes": {},
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
To update the Status of an ItemReturnJob
, utilize the ItemReturnJobStatusChangeAction
API Action:
id of the Item Return Job
POST /api/itemreturnjobs/{itemReturnJobId}/actions HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"name": "StartItemReturnJob",
"version": 1
}
{
"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",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"notReturnableLineItems": [
{
"article": {
"customAttributes": {},
"imageUrl": "text",
"tenantArticleId": "4711",
"title": "Cologne Water",
"titleLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"weight": 1,
"attributes": [
{
"category": "descriptive",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"itemReturns": [],
"anonymized": false,
"customAttributes": {},
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
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:
id of the Item Return Job
POST /api/itemreturnjobs/{itemReturnJobId}/actions HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"name": "StartItemReturnJob",
"version": 1
}
{
"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",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"notReturnableLineItems": [
{
"article": {
"customAttributes": {},
"imageUrl": "text",
"tenantArticleId": "4711",
"title": "Cologne Water",
"titleLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"weight": 1,
"attributes": [
{
"category": "descriptive",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"itemReturns": [],
"anonymized": false,
"customAttributes": {},
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
For updating an existing ItemReturn
, utilize the following API Actions:
id of the Item Return Job
id of the Item Return
POST /api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"name": "AnnounceItemReturn",
"itemReturnJobVersion": 1
}
{
"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",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"notReturnableLineItems": [
{
"article": {
"customAttributes": {},
"imageUrl": "text",
"tenantArticleId": "4711",
"title": "Cologne Water",
"titleLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"weight": 1,
"attributes": [
{
"category": "descriptive",
"context": {
"type": "FACILITY_GROUP",
"value": "text"
},
"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,
"scannableCodes": [
"text"
],
"customAttributes": {},
"recordableAttributes": [
{
"group": "general",
"keyLocalized": {
"de_DE": "Wert",
"en_US": "Value",
"ru_RU": "значение"
},
"recordingRule": "MANDATORY",
"value": "Germany"
}
]
}
],
"itemReturns": [],
"anonymized": false,
"customAttributes": {},
"created": "2020-02-03T08:45:51.525Z",
"lastModified": "2020-02-03T09:45:51.525Z",
"version": 42
}
Change the Status via
ItemReturnStatusChange
Replace items via
ItemReturnReplaceReturnedLineItemsAction
Remove the
ItemReturn
from theItemReturnJob
usingDeleteItemReturnAction
Last updated
Was this helpful?