Open a return request
Opens a return request for one or more lines of an order. Every requested line starts in a PENDING status; Sibi staff then approve or deny each line, and the outcome arrives on the order.return-request.item-approved and order.return-request.item-denied webhook events — see Order Return Requests events.
Check line eligibility first with GET /orders/{orderId}/returns/eligibility. A request for a line that is not eligible, is not on the order, appears twice, or exceeds the returnable quantity is rejected with a 400 carrying one of the codes: RETURN_INVALID_CONDITION, RETURN_INVALID_QUANTITY, RETURN_DUPLICATE_LINE, RETURN_LINE_NOT_ON_ORDER, RETURN_ITEM_NOT_ELIGIBLE, RETURN_QUANTITY_EXCEEDED.
POST
/{orderId}/returnsAuthorization
AuthorizationBearer token · headerrequiredAPI token from the SIBI developer dashboard (developer.sibipro.com), sent as `Authorization: Bearer <token>`.
Scopes:
create:returnsPath parameters
orderIdstringrequiredThe order the return data belongs to.
min length 1
Request body
application/jsonitemsReturnRequestItemInput[]requiredThe lines to return. At least one; each must reference a distinct order line.
min items 1 · max items 100
Show propertiesHide properties
Array of
ReturnRequestItemInputorderLineItemIdstringrequiredThe order line to return, referencing the order line by its itemId.
quantityintegerrequiredUnits of the order line to return. At least one, and bounded by the ordered quantity.
conditionstringrequiredPhysical condition of the item at intake.
Allowed:
UNOPENEDOPENED-UNUSEDINSTALLEDDAMAGEDrequestReasonstringrequiredWhy the line is being returned.
min length 1
Responses
201The return request was opened. Every line starts PENDING.
idstringrequiredThe unique identifier for the return request.
orderIdstringrequiredThe order the returned lines belong to.
createdAtstringrequiredISO 8601 timestamp of when the request was created.
updatedAtstringrequiredISO 8601 timestamp of the most recent change.
itemsReturnRequestItem[]requiredThe requested lines, each carrying its current status.
Show propertiesHide properties
Array of
ReturnRequestItemorderLineItemIdstringrequiredLinks back to the order line (Order line itemId).
quantityintegerrequiredHow many units of the order line this covers.
conditionstringrequiredPhysical condition reported at intake.
requestReasonstringrequiredWhy the line was requested for return.
statusstringrequiredPer-item status, derived from the latest decision (PENDING when none exists).
Allowed:
PENDINGAPPROVEDDENIEDlatestDecisionReturnItemDecision | nullrequiredThe most recent decision on this line; null while PENDING.
Show propertiesHide properties
outcomestringrequiredThe decision recorded for the line.
Allowed:
APPROVEDDENIEDdenialReasonstring | nullrequiredSet only when the outcome is DENIED.
decidedAtstringrequiredISO 8601 timestamp of when the decision was made.
400Bad request - Invalid input data. See the operation description for the possible error codes.
codestringrequiredError code indicating the type of error
Allowed:
VALIDATION_ERRORRETURN_INVALID_CONDITIONRETURN_INVALID_QUANTITYRETURN_DUPLICATE_LINERETURN_LINE_NOT_ON_ORDERRETURN_ITEM_NOT_ELIGIBLERETURN_QUANTITY_EXCEEDEDmessagestringrequiredHuman-readable error message explaining what went wrong
detailsobject[]Detailed validation errors when applicable
Show propertiesHide properties
Array of
objectfieldstringrequirederrorstringrequired401Unauthorized - Missing or invalid authentication
codestringrequiredError code indicating the type of error
messagestringrequiredHuman-readable error message explaining what went wrong
detailsobject[]Detailed validation errors when applicable
Show propertiesHide properties
Array of
objectfieldstringrequirederrorstringrequired403Forbidden - the token was minted for the other environment, is not a Public REST API token, does not carry the scope this operation requires, or targeted the test environment (the Returns API is production-only)
codestringrequiredError code indicating the type of error
messagestringrequiredHuman-readable error message explaining what went wrong
detailsobject[]Detailed validation errors when applicable
Show propertiesHide properties
Array of
objectfieldstringrequirederrorstringrequired404Not found - no order with the given id is visible to the caller, or its return data could not be resolved
codestringrequiredError code indicating the type of error
messagestringrequiredHuman-readable error message explaining what went wrong
detailsobject[]Detailed validation errors when applicable
Show propertiesHide properties
Array of
objectfieldstringrequirederrorstringrequired500Internal server error
codestringrequiredError code indicating the type of error
messagestringrequiredHuman-readable error message explaining what went wrong
detailsobject[]Detailed validation errors when applicable
Show propertiesHide properties
Array of
objectfieldstringrequirederrorstringrequiredRequest
curl -X POST "https://api.sibipro.com/orders/SIBI-12345678/returns" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"orderLineItemId": "OLI-0001",
"quantity": 1,
"condition": "UNOPENED",
"requestReason": "Ordered the wrong size"
}
]
}'const response = await fetch("https://api.sibipro.com/orders/SIBI-12345678/returns", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"items": [
{
"orderLineItemId": "OLI-0001",
"quantity": 1,
"condition": "UNOPENED",
"requestReason": "Ordered the wrong size"
}
]
})
});Response
{
"id": "RET-12345XYZ",
"orderId": "SIBI-12345678",
"createdAt": "string",
"updatedAt": "string",
"items": [
{
"orderLineItemId": "string",
"quantity": 0,
"condition": "UNOPENED",
"requestReason": "string",
"status": "PENDING",
"latestDecision": {
"outcome": "APPROVED",
"denialReason": "string",
"decidedAt": "string"
}
}
]
}{
"code": "VALIDATION_ERROR",
"message": "The request contains invalid parameters",
"details": [
{
"field": "items.0.condition",
"error": "Invalid enum value"
},
{
"field": "items.0.quantity",
"error": "Expected positive integer"
}
]
}{
"code": "string",
"message": "The request contains invalid parameters",
"details": [
{
"field": "items.0.condition",
"error": "Invalid enum value"
},
{
"field": "items.0.quantity",
"error": "Expected positive integer"
}
]
}{
"code": "string",
"message": "The request contains invalid parameters",
"details": [
{
"field": "items.0.condition",
"error": "Invalid enum value"
},
{
"field": "items.0.quantity",
"error": "Expected positive integer"
}
]
}{
"code": "string",
"message": "The request contains invalid parameters",
"details": [
{
"field": "items.0.condition",
"error": "Invalid enum value"
},
{
"field": "items.0.quantity",
"error": "Expected positive integer"
}
]
}{
"code": "string",
"message": "The request contains invalid parameters",
"details": [
{
"field": "items.0.condition",
"error": "Invalid enum value"
},
{
"field": "items.0.quantity",
"error": "Expected positive integer"
}
]
}