Return MCS webhooks

Return webhooks provide real-time visibility into the return lifecycle. Use these events to track returns from authorization through disposition and dispute resolution.

All return events are delivered through the MCS_RETURN_ORDER_STATUS_UPDATE subscription. The specific return event can be identified using the payload.header.eventName field in the webhook payload.

Return lifecycle

The following events may occur during the return process:

MCS_RETURN_ORDER_CANCELLED can occur at any stage of the return lifecycle.

MCS_RETURN_ORDER_DISPUTE_EVENT is triggered when a dispute is raised for a return.

Return authorized

The MCS_RETURN_ORDER_CREATED event is sent when a return request is approved and a return order is created. Use this even to begin tracking the return lifecycle and initiate return related workflows in your systems.

This event notifies you when a return authorization has been created for an order. It is sent when a customer initiates a return request and the return is approved.

Common use cases include:

Create a return record in your order management system.
Initiate return-related workflows.
Track the beginning of the return lifecycle.

Sample webhook payload

The following example shows the payload structure returned when a return authorization is created.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:28:12.609Z", "eventId": "f876bb10-39d6-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "orderType": "MARKET_PLACE", "orderLines": [ { "purchaseOrderNo": "108913558628108", "salesOrderLineNo": 10001, "lineNo": 1, "quantity": { "measurementValue": 1, "unitOfMeasure": "EACH" }, "salesOrderLineId": 1, "faultCategory": "CUSTOMER", "returnReason": "1003", "shipmentId": "ac1a456d-e937-4328-a7df-a5290f2de33b", "orderProduct": { "offerId": { "legacySellerId": "101090674", "legacyItemId": "5344521530", "offerId": "48FD3EAA2CB539B084D00E2F17DFF296" }, "sku": "sku-07080832757382", "productName": "Dish Drying Rack, 2-Tier Large Dish Racks with Drainboard, Utensil Holder, Cups Holder" }, "lineQuantityInfo": [ { "statusDescription": "Market Place Return Initiated", "status": "MARKET_PLACE_RETURN_INITIATED", "statusCode": 1000, "statusQuantity": { "measurementValue": 1, "unitOfMeasure": "EACH" } } ] } ], "salesOrderNo": "MreturnsWebhooktest8623F639968", "returnOrderNo": "returnTest001" }, "header": { "partnerName": "mpcoeewfsseller2", "eventName": "MCS_RETURN_ORDER_CREATED", "partnerId": "10900075044" } }
}

Label generated

The MCS_RETURN_ORDER_LABEL_GENERATED event is sent when a return shipping label is generated and return shipment details become available. Use this event to capture tracking information, carrier details, and return label information.

This event notifies you when a return shipping label has been generated and return shipment details become available. This event is sent when a return label is created for an approved return request and tracking information is available.

Common use cases include:

Capture return tracking information in your systems.
Update customer facing return status and tracking pages.
Monitor return shipment activity.
Prepare downstream workflows related to return processing.

Sample webhook payload

The following example shows the payload returned when a return shipping label is generated. Use the carrier and tracking information to monitor and return shipments and the label details to access return shipping labels.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:28:15.038Z", "eventId": "f9e95de0-39d6-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "orderType": "MARKET_PLACE", "returnLineGroups": [ { "rcType": "WFS", "returnFulfillment": { "shipFrom": { "address": { "city": "Blairstown", "countryCode": "USA", "postalCode": "07825", "addressLineOne": "3 Westview Dr", "stateOrProvinceCode": "NJ" }, "phone": { "completeNumber": "8622266481" }, "name": { "firstName": "<first_name>", "lastName": "<last_name>", "completeName": "Jetlir Rizvani" }, "email": { "emailAddress": "[email protected]" } }, "destinationId": "9074", "fulfillmentType": "WRCFDX" }, "groupNo": 1, "returnOrderLines": [ { "lineNo": 1, "quantity": { "measurementValue": 1, "unitOfMeasure": "EACH" }, "salesOrderLineId": 1 } ], "labels": [ { "labelImageURL": "https://example.com/images/mock-product-image.jpg", "isZPL": false, "labelImageInfo": [ { "imageURL": "https://example.com/images/mock-product-image.jpg", "type": "DEFAULT" } ], "receivingMode": "9074", "carrierInfoList": [ { "serviceType": "FedEx Ground", "carrierName": "FEDEX", "trackingNo": "275148936441", "trackingUrl": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=275148936441", "carrierId": "11" } ] } ] } ], "salesOrderNo": "MreturnsWebhooktest8623F639968", "returnOrderNo": "returnTest001" }, "header": { "partnerName": "mpcoeewfsseller2", "eventName": "MCS_RETURN_ORDER_LABEL_GENERATED", "partnerId": "10900075044" } }
}

Return canceled

The MCS_RETURN_ORDER_CANCELLED event is sent when a return request is canceled before return processing is completed. A return may be canceled by the customer or by the system before the return item is received.

Common use cases include:

Updating return records in your systems.
Stopping pending return related workflows.
Maintaining accurate return status information.

Sample webhook payload

The following example shows the payload returned when. return request is canceled.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:17:07.307Z", "eventId": "5be9b3b0-39d5-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "orderType": "STAGE_RETURN", "orderLines": [ { "salesOrderLineNo": 1, "lineNo": 1, "quantity": { "measurementValue": 1, "unitOfMeasure": "EACH" }, "salesOrderLineId": 1, "shipmentId": "ae6d0d04-e727-4ea9-8b53-4d6ffe7da8d2", "lineQuantityInfo": [ { "statusDescription": "Return Cancelled", "status": "RETURN_CANCELLED", "statusCode": 9000, "statusQuantity": { "measurementValue": 1, "unitOfMeasure": "EACH" } }, { "statusDescription": "Stage Return Initiated", "status": "STAGE_RETURN_INITIATED", "statusCode": 900, "statusQuantity": { "measurementValue": 0, "unitOfMeasure": "EACH" } } ] } ], "salesOrderNo": "string", "returnOrderNo": "string" }, "header": { "partnerName": "string", "eventName": "MCS_RETURN_ORDER_CANCELLED", "partnerId": "string" } }
}

Package in transit

The MCS_RETURN_ORDER_IN_TRANSIT event is sent when a return package has been received by the carrier and is in transit to the return processing center. This event indicates that the return shipment is actively moving through the carrier network.

Common use cases include:

Tracking return shipment progress.
Updating return status in your systems.
Providing visibility into return transit activity.
Monitoring carrier movement and delivery milestones.

Sample webhook payload

The following example shows the payload returned when a return package is in transit.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:15:38.935Z", "eventId": "373d3470-39d5-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "returnLineGroups": [ { "groupNo": 1, "status": "RETURN_IN_TRANSIT" } ], "salesOrderNo": "200011930338488", "returnOrderNo": "164519806762473284" }, "header": { "partnerName": "string", "eventName": "MCS_RETURN_ORDER_IN_TRANSIT", "partnerId": "10900075044" } }
}

Delivered to return center

The MCS_RETURN_ORDER_DELIVERED_AT_RETURN_CENTER event is sent when a return package is delivered to and scanned at a return processing center. This event indicates that the return shipment has reached its destination and is ready for inspection and processing.

Common use cases include:

Confirming receipt of the return shipment.
Updating return status in your systems.
Tracking progress through the return lifecycle.
Preparing for return inspection and disposition processing

Sample wehbook payload

The following example shows the payload returned when a return package is delivered to a return processing center.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:12:23.758Z", "eventId": "c2e78ee0-39d4-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "returnLineGroups": [ { "groupNo": 1, "status": "DELIVERED_AT_RETURN_CENTER" } ], "salesOrderNo": "200011950418204", "returnOrderNo": "164542991994374203" }, "header": { "partnerName": "string", "eventName": "MCS_RETURN_ORDER_DELIVERED_AT_RETURN_CENTER", "partnerId": "10900075044" } }
}

Return received

The MCS_RETURN_ORDER_RECEIVED event is sent when a returned item has been received, inspected, and processed at a return processing center. This event includes a disposition code that indicates the outcome of the inspection and how the return item was handled.

Common use cases include:

Determining the final outcome of a return.
Updating return status in your systems.
Reconciling return processing results.
Monitoring return disposition decisions.

Sample wehbook payload

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-04T07:08:18.061Z", "eventId": "30752bd0-39d4-11ef-beff-5db663a3d2a8" }, "payload": { "payload": { "orderType": "MARKET_PLACE", "orderLines": [ { "salesOrderLineNo": 10001, "lineNo": 1, "quantity": { "measurementValue": 1, "unitOfMeasure": "EACH" }, "salesOrderLineId": 1, "shipmentId": "6d635d8c-9452-4d61-87a9-62a1dd18df0e", "inspectionComments": "SELLABLE", "dispositionCode": "RESTOCK" } ], "salesOrderNo": "200011726691111", "returnOrderNo": "160251989959483442" }, "header": { "partnerName": "mpcoeewfsseller2", "eventName": "MCS_RETURN_ORDER_RECEIVED", "partnerId": "10900075044" } }
}

Disposition codes

A disposition code indicates the outcome of the return inspection and how the returned item was handled after it was received and processed.

Code	Description
`RESTOCK`	Item is in sellable condition and will be returned to inventory.
`DISPOSE`	Item cannot be resold and will be disposed of.
`LIQUIDATION`	Item will be sold through liquidation channels.
`RTV`	Item will be returned to the vendor.
`DONATE`	Item will be donated.
`FRAUD`	Item has been identified as a fraudulent return.
`POTENTIAL_FRAUD`	Item has been flagged for fraud review.

Return dispute

The MCS_RETURN_ORDER_DISPUTE_EVENT event is sent when a dispute is raised for a return. This event includes dispute details and status information that can be used to track the review and resolution of disputed items.

Common use cases include:

Tracking disputed returns.
Monitoring dispute outcomes.
Updating return records with dispute information.
Routing disputed returns for review and ingestion.

Sample webhook payload

The following example shows the payload returned when a dispute is raised for a return.

{ "source": { "eventType": "MCS_RETURN_ORDER_STATUS_UPDATE", "eventFilters": null, "eventTime": "2024-07-10T07:27:57.744Z", "eventId": "ee150300-3e8d-11ef-afa8-d1aa32259641" }, "payload": { "payload": { "orderType": "MCS", "orderLines": [ { "purchaseOrderNo": "108904136993006", "salesOrderLineNo": 1, "lineNo": 1, "quantity": { "measurementValue": 1, "unitOfMeasure": "EACH" }, "salesOrderLineId": 1, "faultCategory": "CUSTOMER", "returnReason": "Changed Mind", "shipmentId": "71751efb-19f2-4881-8da3-3cb2ca32a828", "lineDispute": { "disputeCreationTime": "2024-07-08T10:34:14.000Z", "disputeDescription": "Return received: incorrect item", "disputeDecisionTime": "2024-07-08T10:53:44.000Z", "upc": "00658723904947", "disputeReasonCode": "20", "currentDisputeStatus": "APPROVED" }, "clientReasonCode": "1001", "orderProduct": { "productName": "Product Name" } } ], "salesOrderNo": "100000426803416", "returnOrderNo": "136831327046653448" }, "header": { "partnerName": "string", "eventName": "MCS_RETURN_ORDER_DISPUTE_EVENT", "partnerId": "10900075044" } }
}

Dispute status values

A dispute status indicates the current state of the dispute review process.

Status	Description
`PENDING`	The dispute is under review.
`APPROVED`	The dispute was approved.
`REJECTED`	The dispute was rejected.

Updated about 1 hour ago

Did this page help you?