Start a return (Beta)

Beta — this endpoint is unstable; its request and response shapes may change.

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 returnRequests 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 `sku` does not match any line on the order
`RETURN_AMBIGUOUS_SKU`	The `sku` matches more than one line on the order, so it cannot identify a single line to return
`RETURN_ITEM_NOT_ELIGIBLE`	Policy or current state does not allow returning this line — see the line’s `reasonCode` (e.g. `ALREADY_REQUESTED` when a return request already exists for it, `RETURN_WINDOW_EXPIRED`, `ALREADY_RETURNED`)
`RETURN_QUANTITY_EXCEEDED`	The requested quantity exceeds what remains returnable on the line

POST/orders/{orderId}/return-requests

Authorization

AuthorizationBearer token · headerrequired

A Sibi Public API token or access token, 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

skustringrequired

The product SKU of the order line to return, correlating to the order's lineItems[].sku. Must match exactly one line on the order.

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.

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

skustringrequired

Product SKU of the returned line (correlates to the order's lineItems[].sku).

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

denialReasonstring | nullrequired

Why the line was denied; set only when status is Denied, null otherwise.

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_AMBIGUOUS_SKURETURN_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/return-requests' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "sku": "GDF510PSRSS",
      "quantity": 1,
      "condition": "UNOPENED",
      "requestReason": "Ordered the wrong size"
    }
  ]
}'

const response = await fetch("https://api.sibipro.com/orders/SIBI-12345678/return-requests", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"items\": [\n    {\n      \"sku\": \"GDF510PSRSS\",\n      \"quantity\": 1,\n      \"condition\": \"UNOPENED\",\n      \"requestReason\": \"Ordered the wrong size\"\n    }\n  ]\n}"
});

Response

{
  "orderId": "SIBI-12345678",
  "createdAt": "string",
  "updatedAt": "string",
  "items": [
    {
      "sku": "GDF510PSRSS",
      "quantity": 0,
      "condition": "UNOPENED",
      "requestReason": "string",
      "status": "Pending",
      "denialReason": "string"
    }
  ]
}

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input parameters"
}

{
  "code": "RETURN_ITEM_NOT_ELIGIBLE",
  "message": "This item is not eligible for return."
}

{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token"
}

{
  "code": "TOKEN_ENVIRONMENT_MISMATCH",
  "message": "A test token was used against the production API. Test tokens only work against the Sibi test environment; use a production token here."
}

{
  "code": "REST_TOKEN_REQUIRED",
  "message": "This endpoint only accepts Public REST API tokens. Create one at https://developer.sibipro.com."
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "The presented token is missing the `create:returns` scope, which this endpoint requires. Create a token with the scopes you need at https://developer.sibipro.com."
}

{
  "code": "NOT_AVAILABLE_IN_TEST",
  "message": "The Returns API is not available in the test environment."
}

{
  "code": "ORDER_NOT_FOUND",
  "message": "Unable to find order with id: SIBI-12345678"
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}