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}/returns

Authorization

AuthorizationBearer token · headerrequired

API token from the SIBI developer dashboard (developer.sibipro.com), sent as Authorization: Bearer <token>.

Scopes:create:returns

Path parameters

orderIdstringrequired

The order the return data belongs to.

min length 1

Request body

application/json

itemsReturnRequestItemInput[]required

The lines to return. At least one; each must reference a distinct order line.

min items 1 · max items 100

Show properties

Array of ReturnRequestItemInput

orderLineItemIdstringrequired

The order line to return, referencing the order line by its itemId.

quantityintegerrequired

Units of the order line to return. At least one, and bounded by the ordered quantity.

conditionstringrequired

Physical condition of the item at intake.

Allowed:UNOPENEDOPENED-UNUSEDINSTALLEDDAMAGED

requestReasonstringrequired

Why the line is being returned.

min length 1

Responses

201

The return request was opened. Every line starts PENDING.

idstringrequired

The unique identifier for the return request.

orderIdstringrequired

The order the returned lines belong to.

createdAtstringrequired

ISO 8601 timestamp of when the request was created.

updatedAtstringrequired

ISO 8601 timestamp of the most recent change.

itemsReturnRequestItem[]required

The requested lines, each carrying its current status.

Show properties

Array of ReturnRequestItem

orderLineItemIdstringrequired

Links back to the order line (Order line itemId).

quantityintegerrequired

How many units of the order line this covers.

conditionstringrequired

Physical condition reported at intake.

requestReasonstringrequired

Why the line was requested for return.

statusstringrequired

Per-item status, derived from the latest decision (PENDING when none exists).

Allowed:PENDINGAPPROVEDDENIED

latestDecisionReturnItemDecision | nullrequired

The most recent decision on this line; null while PENDING.

Show properties

outcomestringrequired

The decision recorded for the line.

Allowed:APPROVEDDENIED

denialReasonstring | nullrequired

Set only when the outcome is DENIED.

decidedAtstringrequired

ISO 8601 timestamp of when the decision was made.

400

Bad request - Invalid input data. See the operation description for the possible error codes.

codestringrequired

Error code indicating the type of error

Allowed:VALIDATION_ERRORRETURN_INVALID_CONDITIONRETURN_INVALID_QUANTITYRETURN_DUPLICATE_LINERETURN_LINE_NOT_ON_ORDERRETURN_ITEM_NOT_ELIGIBLERETURN_QUANTITY_EXCEEDED

messagestringrequired

Human-readable error message explaining what went wrong

detailsobject[]

Detailed validation errors when applicable

Show properties

Array of object

fieldstringrequired

errorstringrequired

401

Unauthorized - Missing or invalid authentication

codestringrequired

Error code indicating the type of error

messagestringrequired

Human-readable error message explaining what went wrong

detailsobject[]

Detailed validation errors when applicable

Show properties

Array of object

fieldstringrequired

errorstringrequired

403

Forbidden - 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)

codestringrequired

Error code indicating the type of error

messagestringrequired

Human-readable error message explaining what went wrong

detailsobject[]

Detailed validation errors when applicable

Show properties

Array of object

fieldstringrequired

errorstringrequired

404

Not found - no order with the given id is visible to the caller, or its return data could not be resolved

codestringrequired

Error code indicating the type of error

messagestringrequired

Human-readable error message explaining what went wrong

detailsobject[]

Detailed validation errors when applicable

Show properties

Array of object

fieldstringrequired

errorstringrequired

500

Internal server error

codestringrequired

Error code indicating the type of error

messagestringrequired

Human-readable error message explaining what went wrong

detailsobject[]

Detailed validation errors when applicable

Show properties

Array of object

fieldstringrequired

errorstringrequired

Request

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: "{\n  \"items\": [\n    {\n      \"orderLineItemId\": \"OLI-0001\",\n      \"quantity\": 1,\n      \"condition\": \"UNOPENED\",\n      \"requestReason\": \"Ordered the wrong size\"\n    }\n  ]\n}"
});

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"
    }
  ]
}