Update a custom field
const url = 'https://api.usesonora.com/v1/customer-fields/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"label":"example","options":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.usesonora.com/v1/customer-fields/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "label": "example", "options": [ "example" ] }'Rename a custom field, or add options to a select field. The key and every customer’s value stay as they are, so nothing reading the field by key notices a rename. A field’s type can’t change, and a select’s options can be added and reordered but not removed: customers may hold them. A label another field already shows is 409 customer_field_exists.
Requires the custom-fields:manage scope. API keys only.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The field’s key, as GET /customer-fields lists it.
Request Bodyrequired
Section titled “Request Bodyrequired”What to change. The key, the type and every customer’s value stay as they are.
object
How Sonora shows the field. No other field may show the same label, ignoring case; runs of spaces are kept as one.
A select field’s options, in the order to show them: every option it has, plus any to add. Leaving one out is 422, since customers may hold it. Adding is 422 past 50 options, or past the field’s own count if it already has more, and an option added must be 1 to 100 characters.
Examplegenerated
{ "label": "example", "options": [ "example" ]}Responses
Section titled “Responses”The field, as saved.
A custom field on customers.
object
The key in a customer’s customFields.
date is YYYY-MM-DD; datetime an ISO 8601 instant; select one of options (or several, with multiple); user a list of people.
How the value is meant: currency, percentage, email, url, phone, … Null when it’s plain.
Whether the value is a list: a multi-select, or a user field holding several people.
Example
{ "type": "string"}invalid_json: The request body is not valid JSON.
invalid_request: A parameter or body field is missing, malformed or unknown; details.issues names each.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}insufficient_scope: The key or token lacks the scope this endpoint needs, and details.required names it; or an OAuth access token called an endpoint only an API key can.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}customer_field_not_found: No custom field with that key, or not one Sonora shows: fields an import hid or marked sensitive are never found.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}customer_field_exists: A custom field already has that label; details.key names it when it’s one the API shows.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}payload_too_large: The request body is too large; details.maxBytes gives the limit.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}invalid_fields: A field’s value can’t be saved, so nothing was; details.issues names each field and why.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}rate_limited: Too many requests for this key; retry after Retry-After seconds.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}Try it
Try it runs the reference's read endpoints, and this one changes data, so it needs an API key with the custom-fields:manage scope. Create a key in Sonora under Settings → API and call it from your own code.