BrainerceEdit the items of an order
Adds a product, removes a line or changes a quantity on an order that has not shipped. Each items entry is { index, quantity } (an existing line by its position in the order items; quantity: 0 removes it) or { productId, variantId?, quantity } (a product to add). The request carries no prices: a changed line keeps the price it was sold at, an added line gets the catalog price of the order channel. Stock is held for the added units and handed back for the removed ones in the same step.
Money is never moved. Nothing is charged and nothing is refunded. A paid order whose total rose becomes partially_paid and balanceDue is the positive amount the buyer still owes; one whose total fell stays paid and balanceDue is negative, the amount the store owes the buyer, which the merchant refunds outside this call. An unpaid order simply has a new total.
Discounts and shipping: a percentage coupon is recomputed on the new subtotal, a fixed coupon is kept (capped when the lines it applies to no longer cover it). Automatic discount rules and shipping are not recalculated (see warnings). Tax is re-quoted when the order had a computed tax breakdown.
Refused with 400 (the reason is in the message): the order has shipped or was partly fulfilled, is CANCELLED, REFUNDED or COMPLETED, a shipping label is live, it carries a refund, it is not pending, paid or partially_paid financially, it was charged in another currency than the store currency, a gift card paid part of it or is one of its lines, it was imported (view-only), or the edit would leave no items (cancel the order instead). A bundle line can only be removed, and a line with add-ons or customer input can only be removed; a bundle cannot be added. A product that cannot be held in the requested quantity answers 400 with code: "INSUFFICIENT_STOCK".
Send expectedUpdatedAt (the updatedAt of the preview or of the order you read) to get 409 instead of an edit applied on top of a change someone else made. Supports Idempotency-Key header for safe retries.
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
Header Parameters
Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.
- Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
- Reusing a key with a different body returns
409 Conflictwithcode: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response. - Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
- Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
- Sending this header on a
GETreturns400withcode: "IDEMPOTENCY_KEY_NOT_SUPPORTED"— GETs are already idempotent. - Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.
length <= 255The lines to change, at least one. Each entry is either { index, quantity } (an existing line; 0 removes it) or { productId, variantId?, quantity } (a product to add). There are no prices in the request.
1 <= itemsThe order updatedAt as you last read it (ISO 8601, for example the updatedAt of the preview). When the order changed since, the call answers 409 and changes nothing.
curl -X PATCH "https://api.brainerce.com/api/v1/orders/string/items" \ -H "Idempotency-Key: string" \ -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"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/items"
}{
"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"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/items"
}{
"statusCode": 409,
"code": "CONFLICT",
"message": "The request conflicts with the current state of the resource",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/items"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/store"
}