BrainerceAsk to return items of an order
Checked against the return rules on the server: the order must have shipped, be inside the return window, and the quantities and lines must still be returnable. Sending the same clientRequestId again replays the first request instead of opening a second one. The merchant approves or declines (or the store approves automatically).
For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.
In: header
Path Parameters
Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.
Header Parameters
Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.
Customer token as Bearer <token>, returned by customers/login, customers/register or the OAuth callback. Expires after 7 days. It is a customer token, never an API key.
Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.
The order to return items of.
length <= 64The lines to send back.
1 <= items <= 50One reason for the whole request. Optional when every line carries its own reasonCode.
length <= 64length <= 1000"REFUND""REFUND" | "EXCHANGE"A retry of the same request (a double tap) with the same value replays the first one.
length <= 64curl -X POST "https://api.brainerce.com/api/vc/string/customers/me/returns" \ -H "origin: string" \ -H "authorization: string" \ -H "X-SDK-Version: string" \ -H "Content-Type: application/json" \ -d '{ "orderId": "string", "items": [ { "lineId": "string", "quantity": 1 } ] }'{
"id": "string",
"number": "R-1001",
"orderId": "string",
"orderNumber": "string",
"status": "REQUESTED",
"resolution": "REFUND",
"reasonCode": "string",
"customerNote": "string",
"declineMessage": "string",
"requestedAt": "2019-08-24T14:15:22Z",
"approvedAt": "2019-08-24T14:15:22Z",
"receivedAt": "2019-08-24T14:15:22Z",
"completedAt": "2019-08-24T14:15:22Z",
"cancelledAt": "2019-08-24T14:15:22Z",
"items": [
{
"id": "string",
"lineId": "string",
"name": "string",
"sku": "string",
"quantity": 0,
"receivedQuantity": 0,
"reasonCode": "string"
}
]
}{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "name should not be empty, price must be a positive number",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/customers/me/returns"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/customers/me/returns"
}{
"statusCode": 403,
"code": "INSUFFICIENT_SCOPE",
"message": "API key does not have the required scope: products:write",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/customers/me/returns"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/customers/me/returns"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/customers/me/returns"
}