When an item is returned, an additional set of logs are generated. Return notifications are simple and follow a structured schema that provides data about the return case such as the date and return reason, the item and order it belonged to, and similar information.
The following notifications are outlined in this guide:
- Create Return Notification – Sent when a return is created and enters the Open Return state.
- Accept Return Notification – Sent when a return is accepted and goes to Accepted Return state.
- Reject Return Notification – Sent when a return is rejected and the order returns to the Fulfilled Order state.
- Clear Return Notification – Sent when the return is completed with any refunds processed and sent to the Cleared Return state.
- Re-Open Return Notification – Sent when a return is accepted and then returned to the Open Return status for changes.
- Return Failure Notification – Sent when there is a transactional error while processing a refund.
Return Event Notifications Parameters
The basic information that all Return Event Notifications provide is outlined below, though some notifications may include an additional parameter to provide details specific to that step of the return process. These cases are noted above the relevant example below.
| Field | Type | Parent | Description |
| eventTypeID | string | Always shown as ’return_created’, ’return_accepted’, etc. | |
| status | string | The status of the return (such as open or closed) | |
| source | string | Whether the return was initiated in the admin interface, the Customer Care interface, or otherwise | |
| orderID | integer | The identifier of the order the return is being created on | |
| shipmentID | integer | The identifier of the shipment that the return was associated with | |
| externalOrderID | string | Client-generated unique identifier for the Order sent to Kibo | |
| returnID | integer | A unique identifier for the return | |
| manufacturerID | integer | A unique identifier for a manufacturer | |
| catalogID | string | A unique identifier for the catalog | |
| retailerID | integer | A unique identifier for a retailer | |
| returnLocationID | integer | A unique identifier for a location. | |
| externalStoreID | string | The fulfiller’s identifier for a location. | |
| returnLocationName | string | The name of the location. | |
| createdTime | string | The date and time that the return was created (date-time format) | |
| acceptedTime | string | The date and time that the return was accepted (date-time format) | |
| clearedTime | string | The date and time that the return was cleared (date-time format) | |
| returnItems | array | A list of the items that are being returned | |
| returnItemID | integer | returnItems | A unique identifier, different from the itemID,that denotes the line-item being returned |
| itemID | integer | returnItems | The item’s identifier. |
| quantity | integer | returnItems | The quantity of the line-item that is being returned |
| status | string | returnItems | The status of the item in return |
| reason | string | returnItems | The reason that the item is being returned (such as “did not fit” or “changed my mind”) |
| partNumber | integer | returnItems | The part number of the line-item that is being returned |
| upc | string | returnItems | The UPC code for the line-item that is being returned |
| sku | string | returnItems | The SKU code for the line-item that is being returned |
| orderType | string | The type of the order (e.g. “IN_STORE_PICKUP”) | |
| data | object | Empty | |
| scope | object | Contains the mfgID and catalogID that the order belongs to. |
Create Return Notification
A Create Return Notification is triggered when a return is created on a fulfilled order, putting the order into the “RETURN_INITIATED” state and placing the return itself into the “OPEN_RETURN” status. This example shows the creation of an example return.
{
"eventTypeID":"return_created",
"status":"Open",
"source":"ADMIN",
"orderID":"012345",
"shipmentID":"543210",
"externalOrderID":"AM_TEST_1531922876",
"returnID":01010101,
"manufacturerID":"11111",
"catalogID":"0",
"retailerID":"00000",
"returnLocationID":null,
"externalStoreID":null,
"returnLocationName":null,
"createdTime":"2018-07-23 14:34:30",
"acceptedTime":null,
"clearedTime":null,
"returnItems":[
{
"returnItemID":"22222",
"itemID":"020202",
"quantity":"2.00",
"status":"pending",
"reason":"Changed my mind",
"partNumber":"TestProduct1",
"upc":null,
"sku":null
}
],
"orderType":null,
"data":null,
"scope":{
"mfgID":"11111",
"catalogID":"0"
}
}Accept Return Notification
An Accept Return Notification is triggered when the created return is accepted by the fulfiller handling the items, which places the return into “RETURN_ACCEPTED” status. This example shows the acceptance of an example return.
{
"eventTypeID":"return_accepted",
"status":"Accepted",
"source":"ADMIN",
"orderID":"012345",
"shipmentID":"543210",
"externalOrderID":"AM_TEST_1531922876",
"returnID":"01010101",
"manufacturerID":"11111",
"catalogID":"0",
"retailerID":"00000",
"returnLocationID":"11111",
"externalStoreID":"1",
"returnLocationName":"ZZZ Store 1",
"createdTime":"2018-07-23 14:34:30",
"acceptedTime":"2018-07-23 14:34:41",
"clearedTime":null,
"returnItems":[
{
"returnItemID":"22222",
"itemID":"020202",
"quantity":"2.00",
"status":"accepted",
"reason":"Changed my mind",
"partNumber":"TestProduct1",
"upc":null,
"sku":null
}
],
"orderType":null,
"data":null,
"scope":{
"mfgID":"11111",
"catalogID":"0"
}
}Reject Return Notification
A Reject Return Notification is triggered when the return is rejected by the fulfiller before completion, which puts the original order back into the “FULFILLED_ORDER” state instead of “RETURN_INITIATED.” It adds one additional parameter to the data body:
| Field | Type | Description |
| returnTotal | number | The total cost of the return that was deleted |
This example shows the deletion of an example return.
{
"eventTypeID":"return_deleted",
"status":"Deleted",
"source":"ADMIN",
"orderID":"012345",
"shipmentID":"543210",
"externalOrderID":"00112233",
"returnID":"01010101",
"manufacturerID":"11111",
"catalogID":"15",
"retailerID":null,
"returnLocationID":null,
"externalStoreID":null,
"returnLocationName":null,
"returnTotal":899.99,
"createdTime":"2018-07-23 23:12:19",
"acceptedTime":null,
"clearedTime":null,
"returnItems":[
{
"returnItemID":"22222",
"itemID":"020202",
"quantity":"1.00",
"status":"pending",
"reason":"Changed my mind",
"partNumber":"TestProduct1",
"upc":null,
"sku":null
}
],
"orderType":null,
"data":null,
"scope":{
"mfgID":"11111",
"catalogID":"15"
}
}Clear Return Notification
A Clear Return Notification is triggered when the return is completed, which includes the successful processing of all refunds and placing the return into “CLEARED_RETURN” status. This example shows the clearing of an example return.
{
"eventTypeID":"return_cleared",
"status":"Cleared",
"source":"ADMIN",
"orderID":"012345",
"shipmentID":"543210",
"externalOrderID":"AM_TEST_1531922876",
"returnID":"01010101",
"manufacturerID":"11111",
"catalogID":"0",
"retailerID":"00000",
"returnLocationID":"11111",
"externalStoreID":"1",
"returnLocationName":"ZZZ Store 1",
"createdTime":"2018-07-23 14:34:30",
"acceptedTime":"2018-07-23 14:34:41",
"clearedTime":"2018-07-24 07:35:09",
"returnItems":[
{
"returnItemID":"22222",
"itemID":"020202",
"quantity":"2.00",
"status":"accepted",
"reason":"Changed my mind",
"partNumber":"TestProduct1",
"upc":null,
"sku":null
}
],
"orderType":null,
"data":null,
"scope":{
"mfgID":"11111",
"catalogID":"0"
}
}Re-Open Return Notification
A Re-Open Return Notification is triggered when a completed, closed return is reopened to make additional line-item returns. This places the return back into the initial “OPEN_RETURN” status. This example shows the reopening of an example return.
{
"eventTypeID":"return_reopened",
"status":"Open",
"source":"CCUI",
"orderID":"012345",
"shipmentID":"543210",
"externalOrderID":"00112233",
"returnID":"01010101",
"manufacturerID":"11111",
"catalogID":"0",
"retailerID":"00000",
"returnLocationID":null,
"externalStoreID":null,
"returnLocationName":null,
"createdTime":"2018-07-23 16:34:05",
"acceptedTime":null,
"clearedTime":null,
"returnItems":[
{
"returnItemID":"999888",
"itemID":"888999",
"quantity":"1.00",
"status":"pending",
"reason":"Customer changed mind",
"partNumber":"0123456789",
"upc":"0123456789",
"sku":"3030303-0922"
},
{
"returnItemID":"666777",
"itemID":"777666",
"quantity":"1.00",
"status":"pending",
"reason":"Customer changed mind",
"partNumber":"0987654321",
"upc":"0987654321",
"sku":"3010301-1388"
},
{
"returnItemID":"444555",
"itemID":"555444",
"quantity":"1.00",
"status":"pending",
"reason":"Customer changed mind",
"partNumber":"01020304",
"upc":"01020304",
"sku":"4010300-0415"
}
],
"orderType":null,
"data":null,
"scope":{
"mfgID":"11111",
"catalogID":"0"
}
}Return Failure Notification
A Return Failure Notification is triggered when a refund fails on the third processing attempt. Like the Rejected Return Notification, Return Failure includes the total value of the return in the notification data. Additionally, note that this notification is sent in addition to the generic Payment Transaction Error Notification.
| Field | Type | Description |
| returnTotal | number | The total value of the return that failed. |
{
"eventTypeID":"return_errored",
"status":"Accepted",
"source":"ADMIN",
"orderID":"0000000",
"shipmentID":"43764077",
"externalOrderID":"T-Live-Testing-aaa_1543512440",
"returnID":"111111",
"manufacturerID":"010101",
"catalogID":"0",
"retailerID":"101010",
"returnLocationID":"22222",
"externalStoreID":"00001",
"returnLocationName":"00001-Example Store",
"returnTotal":373.05,
"createdTime":"2018-11-29 19:29:32",
"acceptedTime":"2018-11-29 19:30:09",
"clearedTime":null,
"returnItems":[
{
"returnItemID":"00011",
"itemID":"00022",
"quantity":"1.00",
"status":"accepted",
"reason":"Changed my mind",
"partNumber":"10111",
"upc":"1234",
"sku":"1234"
},
{
"returnItemID":"00033",
"itemID":"00044",
"quantity":"1.00",
"status":"accepted",
"reason":"Changed my mind",
"partNumber":"20222",
"upc":"1234",
"sku":"1234"
}
],
"orderType":"IN_STORE_PICKUP",
"data":null,
"scope":{
"mfgID":"22222",
"catalogID":"0"
}
}