BrainerceSet custom field values on an order
Merges the supplied values into the order. Omitted keys keep their current value; null clears a non-required field. Values are coerced to the definition type and rejected with a 400 when they cannot be — a key with no active definition is ignored instead, so read the response to confirm what was stored.
Where a value ends up: it shows on the order in the dashboard and travels to every order email as orderCustomFields. It is not returned by any storefront endpoint: the definition's isPublic flag is stored but nothing reads it. No default email template prints that variable — until the merchant adds the block to their template once, a value written here is stored correctly and seen by nobody. Writing a field is not the same as the customer being told.
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 <= 255Values to write, keyed by definition key. This is a MERGE: keys you omit keep their current value. Send null to clear one (a required field refuses this). A key with no active definition on the store is IGNORED rather than rejected, so a caller writing an optional field the merchant has not created yet does not fail the whole request — read the response fields to see what was actually stored.
curl -X PATCH "https://api.brainerce.com/api/v1/orders/string/custom-fields" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "fields": { "licence_key": "ABCD-EFGH-IJKL" } }'{
"orderId": "clx1a2b3c4d5e6f7g8h9",
"fields": {
"licence_key": "ABCD-EFGH-IJKL",
"activated_at": "2026-09-09"
}
}{
"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}/custom-fields"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/custom-fields"
}{
"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}/custom-fields"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/orders/{id}/custom-fields"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/store"
}