BrainercePreview an edit of the items of an order
Shows what PATCH /v1/orders/{id}/items would do with the same body, and writes nothing: the lines after the edit, the totals before and after, the amount that would be owed afterwards (balanceDue), and whether the units an edit adds are in stock (stock). Send an empty items list to learn only whether the order can be edited (editable, reason).
An order that cannot be edited is answered with 200 and editable: false plus the reason, so check editable before relying on the numbers. An entry naming a line that does not exist, or a request that changes nothing, answers 400.
The request carries no prices. A changed line keeps the price it was sold at; an added line is priced from the catalog price of the order channel.
Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.
In: header
Path Parameters
Order ID
The lines to change. An edit cannot remove every line (cancel the order instead). An empty list is allowed on the preview only: it answers whether the order can be edited at all (editable, reason). There are no prices in the request: a changed line keeps the price it was sold at.
The order updatedAt as you last read it (ISO 8601). When the order changed since, the edit is refused with 409 instead of being applied on top of someone else's change.
curl -X POST "https://api.brainerce.com/api/v1/orders/string/items/preview" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "quantity": 2 } ] }'{
"applied": false,
"editable": true,
"reason": "Items can only be edited before the order ships (status is SHIPPED).",
"currency": "USD",
"updatedAt": "2026-10-29T10:15:30.000Z",
"lines": [
{
"index": 0,
"kind": "kept",
"productId": "clx1a2b3c4d5e6f7g8h9",
"variantId": null,
"name": "Blue T-shirt - M",
"sku": "TSH-BLU-M",
"image": "https://cdn.example.com/p/1.jpg",
"quantity": 2,
"unitPrice": "19.90",
"lineTotal": "39.80"
}
],
"removed": [
{
"index": 1,
"productId": "clx1a2b3c4d5e6f7g8h9",
"name": "Blue T-shirt - M",
"quantity": 1
}
],
"before": {
"subtotal": "59.70",
"couponDiscount": "0.00",
"discountAmount": "0.00",
"taxAmount": "10.15",
"shippingAmount": "5.00",
"totalAmount": "74.85"
},
"after": {
"subtotal": "59.70",
"couponDiscount": "0.00",
"discountAmount": "0.00",
"taxAmount": "10.15",
"shippingAmount": "5.00",
"totalAmount": "74.85"
},
"delta": "19.90",
"balanceDue": "19.90",
"financialStatus": "partially_paid",
"warnings": [
"COUPON_PERCENTAGE_RECOMPUTED"
],
"stock": [
{
"productId": "clx1a2b3c4d5e6f7g8h9",
"variantId": null,
"name": "Blue T-shirt - M",
"requested": 2,
"available": 14,
"ok": true
}
]
}{
"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/v1/orders/{id}/items/preview"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/items/preview"
}{
"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/v1/orders/{id}/items/preview"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/items/preview"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/store"
}