Open a return request

Opens a return request for one or more lines of an order. A 201 means the request was opened — not that any line is approved yet. Every requested line starts PENDING.

Learning the outcome: Sibi staff approve or deny each line independently (one request can end with some lines approved and others denied). Learn the result by subscribing to the order.returnrequest.item-approved and order.returnrequest.item-denied webhook events — see Order Return Requests events — or by re-reading the order with GET /orders/{orderId}, whose returns array carries each line’s current status.

A line that is not eligible, is not on the order, appears more than once, or exceeds the returnable quantity is rejected with a 400. The 400 lists every failing line in details[] — each carrying its own code from the set below — and no return request is created unless all lines pass.

Code	Meaning
`RETURN_INVALID_CONDITION`	The `condition` is not one of the accepted values
`RETURN_INVALID_QUANTITY`	The `quantity` is not a positive whole number
`RETURN_DUPLICATE_LINE`	The same order line appears more than once in the request
`RETURN_LINE_NOT_ON_ORDER`	The `orderLineItemId` is not a line on the order
`RETURN_ITEM_NOT_ELIGIBLE`	Policy does not allow returning this line
`RETURN_QUANTITY_EXCEEDED`	The requested quantity exceeds what remains returnable on the line

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": "customer.email",
      "error": "Invalid email"
    },
    {
      "field": "address.postalCode",
      "error": "Invalid"
    }
  ]
}

{
  "code": "string",
  "message": "The request contains invalid parameters",
  "details": [
    {
      "field": "customer.email",
      "error": "Invalid email"
    },
    {
      "field": "address.postalCode",
      "error": "Invalid"
    }
  ]
}

{
  "code": "string",
  "message": "The request contains invalid parameters",
  "details": [
    {
      "field": "customer.email",
      "error": "Invalid email"
    },
    {
      "field": "address.postalCode",
      "error": "Invalid"
    }
  ]
}

{
  "code": "string",
  "message": "The request contains invalid parameters",
  "details": [
    {
      "field": "customer.email",
      "error": "Invalid email"
    },
    {
      "field": "address.postalCode",
      "error": "Invalid"
    }
  ]
}

{
  "code": "string",
  "message": "The request contains invalid parameters",
  "details": [
    {
      "field": "customer.email",
      "error": "Invalid email"
    },
    {
      "field": "address.postalCode",
      "error": "Invalid"
    }
  ]
}