Order Return Requests

Payloads for the order.returnrequest.created, order.returnrequest.item-approved, order.returnrequest.item-denied, and order.returnrequest.updated topics.

A return request covers one or more lines from a single order. It opens with a status of pending for every requested line, and Sibi staff then approve or deny each line individually. Because decisions are made per line, a single request can produce multiple itemApproved and itemDenied events over its lifetime.

Return Request Created

This event is triggered when a return request is first opened. The event will have a topic of order.returnrequest.created.

When a request is created, every line on it is pending review.

`orderId`

The identifier of the order the returned lines belong to.

`items`

The lines requested for return. Always contains at least one entry. Each entry has:

sku - The product SKU of the line being returned, correlating to the order’s lineItems[].sku.
quantity - The number of units requested for return. Always a positive integer.
condition - The condition of the item being returned. One of UNOPENED, OPENED-UNUSED, INSTALLED, or DAMAGED.
requestReason - The reason provided for returning this line.

Example payload

{
  "topic": "order.returnrequest.created",
  "data": {
    "orderId": "ORD-12345XYZ",
    "items": [
      {
        "sku": "GDF510PSRSS",
        "quantity": 2,
        "condition": "UNOPENED",
        "requestReason": "Ordered the wrong size"
      }
    ]
  }
}

Return Request Item Approved

This event is triggered when a single requested line is approved. The event will have a topic of order.returnrequest.item-approved. One event fires per approved line, so a request with several approved lines produces several events.

Approval is Sibi staff confirming the line will be taken back. It starts the return; it does not complete it. Sibi support then emails the person who placed the order to coordinate the return with the distributor, so watch for that email — the next steps come from support, not from this event.

`orderId`

The identifier of the order the returned line belongs to.

`sku`

The product SKU of the approved line, correlating to the order’s lineItems[].sku.

`quantity`

The number of units approved for return. Always a positive integer.

Example payload

{
  "topic": "order.returnrequest.item-approved",
  "data": {
    "orderId": "ORD-12345XYZ",
    "sku": "GDF510PSRSS",
    "quantity": 2
  }
}

Return Request Item Denied

This event is triggered when a single requested line is denied. The event will have a topic of order.returnrequest.item-denied. One event fires per denied line, so a request with several denied lines produces several events.

`orderId`

The identifier of the order the returned line belongs to.

`sku`

The product SKU of the denied line, correlating to the order’s lineItems[].sku.

`denialReason`

The reason the line was denied, as recorded on the decision.

Example payload

{
  "topic": "order.returnrequest.item-denied",
  "data": {
    "orderId": "ORD-12345XYZ",
    "sku": "GDF510PSRSS",
    "denialReason": "Item is outside the return window"
  }
}

Return Request Updated

This event is triggered each time a line on the request is decided — approved or denied. The event will have a topic of order.returnrequest.updated.

Unlike item-approved and item-denied, which each report a single line’s decision, this event carries the full current state of the request: every requested line with its latest status. One decision therefore produces one item-approved or item-denied event and one updated event. Use this topic when you want the whole request’s state from a single event instead of stitching the per-line events together.

This event does not fire when the request is first opened — use order.returnrequest.created for that.

sku - The product SKU of the line being returned, correlating to the order’s lineItems[].sku.
quantity - The number of units requested for return. Always a positive integer.
condition - The condition of the item being returned. One of UNOPENED, OPENED-UNUSED, INSTALLED, or DAMAGED.
requestReason - The reason provided for returning this line.
status - The line’s current status. One of Pending, Approved, or Denied.
denialReason - The reason the line was denied, as recorded on the decision. null unless status is Denied.

Example payload

{
  "topic": "order.returnrequest.updated",
  "data": {
    "orderId": "ORD-12345XYZ",
    "updatedAt": "2025-03-18T16:45:22.456Z",
    "items": [
      {
        "sku": "GDF510PSRSS",
        "quantity": 2,
        "condition": "UNOPENED",
        "requestReason": "Ordered the wrong size",
        "status": "Approved",
        "denialReason": null
      },
      {
        "sku": "DW80R9950US",
        "quantity": 1,
        "condition": "DAMAGED",
        "requestReason": "Arrived dented",
        "status": "Denied",
        "denialReason": "Item is outside the return window"
      }
    ]
  }
}