Settings

The Settings resource exposes your tenant’s locale and business-profile configuration. It is a singleton: every tenant has exactly one settings object, so there are no list, create, or delete endpoints.

Settings vs Account, GET /api/v1/settings returns locale/tax/hours fields. GET /api/v1/account returns a richer object that also includes logo URL and subscription plan. Use Account if you need plan info; use Settings if you need to write locale or tax configuration.

The settings object

{
  "object": "settings",
  "shop_name": "Riverside Repair",
  "timezone": "America/New_York",
  "currency_code": "USD",
  "country_code": "US",
  "tax_rate": 6.625,
  "tax_label": "Sales Tax",
  "tax_apply_default": true,
  "paper_size": "LETTER",
  "primary_service_noun": "repair",
  "business_profile": {
    "name": "Riverside Repair LLC",
    "address1": "123 Main St",
    "address2": null,
    "city": "Springfield",
    "state": "IL",
    "zip": "62701",
    "country": "US",
    "phone": "555-555-0100",
    "email": "info@riversiderepair.com",
    "website": "https://riversiderepair.com",
    "tagline": "Fixed right the first time."
  },
  "business_hours": {
    "mon": { "open": "09:00", "close": "17:00", "closed": false },
    "tue": { "open": "09:00", "close": "17:00", "closed": false },
    "sat": { "closed": true },
    "sun": { "closed": true }
  }
}

Field	Type	Description
`shop_name`	string\|null	Display name of the shop (read-only via this endpoint)
`timezone`	string\|null	IANA timezone identifier (e.g. `America/Chicago`)
`currency_code`	string	ISO 4217 currency code, defaults to `USD`
`country_code`	string	ISO 3166-1 alpha-2 country, defaults to `US`
`tax_rate`	number	Default tax rate as a percentage (e.g. `6.625` for 6.625%)
`tax_label`	string	Label shown on invoices (e.g. `"Sales Tax"`, `"VAT"`)
`tax_apply_default`	boolean	Whether the default tax rate is applied automatically
`paper_size`	string	Print paper size: `"LETTER"` or `"A4"`
`primary_service_noun`	string\|null	The word used for your primary service type (read-only)
`business_profile`	object	Contact and address fields, see sub-fields below
`business_hours`	object	Operating hours keyed by weekday (`mon`–`sun`); read-only via this endpoint

`business_profile` fields

Field	Type	Description
`name`	string\|null	Legal or trade name
`address1`	string\|null	Street address
`address2`	string\|null	Suite, unit, etc.
`city`	string\|null	City
`state`	string\|null	State / province
`zip`	string\|null	Postal code
`country`	string\|null	Country (ISO 3166-1 alpha-2)
`phone`	string\|null	Business phone number
`email`	string\|null	Business contact email
`website`	string\|null	Website URL
`tagline`	string\|null	Short tagline

`business_hours` shape

Each configured day maps to an object:

Field	Type	Description
`open`	string\|null	Opening time in `HH:MM` (24-hour)
`close`	string\|null	Closing time in `HH:MM` (24-hour)
`closed`	boolean	`true` if the shop is closed that day

Days not present in the map have not been configured. Business hours are managed through BenchKey’s Appointments settings and are read-only via the Settings API endpoint.

Retrieve settings

GET /api/v1/settings

Returns the singleton settings object.

Scope required: settings.read

curl

curl https://app.benchkey.com/api/v1/settings \
  -H "Authorization: Bearer bk_live_<tenantId>_<secret>"

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/settings", {
  headers: { Authorization: "Bearer bk_live_<tenantId>_<secret>" },
});
const settings = await res.json();
console.log(settings.timezone);       // "America/New_York"
console.log(settings.tax_rate);       // 6.625
console.log(settings.currency_code);  // "USD"

Response

{
  "object": "settings",
  "shop_name": "Riverside Repair",
  "timezone": "America/New_York",
  "currency_code": "USD",
  "country_code": "US",
  "tax_rate": 6.625,
  "tax_label": "Sales Tax",
  "tax_apply_default": true,
  "paper_size": "LETTER",
  "primary_service_noun": "repair",
  "business_profile": {
    "name": "Riverside Repair LLC",
    "address1": "123 Main St",
    "address2": null,
    "city": "Springfield",
    "state": "IL",
    "zip": "62701",
    "country": "US",
    "phone": "555-555-0100",
    "email": "info@riversiderepair.com",
    "website": "https://riversiderepair.com",
    "tagline": "Fixed right the first time."
  },
  "business_hours": {
    "mon": { "open": "09:00", "close": "17:00", "closed": false },
    "sat": { "closed": true }
  }
}

Update settings

PATCH /api/v1/settings

Updates one or more settings fields. Send only the fields you want to change, missing fields are left unchanged. Input validation runs before writes, but the settings are saved separately. A later save failure can leave earlier changes applied. After an error, retrieve the settings and reconcile the fields you intended to change before retrying.

Returns the re-read settings object reflecting the persisted values.

Scope required: settings.write

Writable fields

Field	Type	Notes
`timezone`	string	IANA timezone identifier
`currency_code`	string	Supported currency code from the list below. Case-insensitive, `"usd"` is accepted and normalized to `"USD"`; leading or trailing whitespace is rejected.
`country_code`	string	Valid ISO 3166-1 alpha-2 code (e.g. `"US"`, `"GB"`). Case-insensitive, `"us"` is accepted and normalized to `"US"`; leading or trailing whitespace is rejected.
`default_tax_rate`	number	Must be between `0` and `100` (inclusive)
`tax_label`	string	Label shown on invoices
`tax_apply_default`	boolean	Whether default tax is applied automatically
`paper_size`	string	`"LETTER"` or `"A4"`
`business_profile`	object	Nested object, see writable sub-fields below

shop_name and primary_service_noun are read-only, supply them and you will receive a 400 invalid_field error.

Supported currencies: USD, CAD, GBP, EUR, AUD, NZD, SGD, KES, MXN, INR, ZAR, BRL, CHF, CZK, RON, MYR, THB, AED, DKK, SEK, NOK, PLN. Zero-decimal currencies such as JPY are not supported. Accepting a country code does not establish signup availability or payment-processor support in that country.

Writable `business_profile` sub-fields

All sub-fields are optional strings (or null to clear):

name, address1, address2, city, state, zip, country, phone, email, website, tagline

The business_profile key performs a merge against the existing value, you only need to supply the sub-fields you want to change. Supply null to explicitly clear a sub-field.

curl

# Update timezone and tax rate
curl -X PATCH https://app.benchkey.com/api/v1/settings \
  -H "Authorization: Bearer bk_live_<tenantId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/Chicago", "default_tax_rate": 8.0, "tax_label": "State Tax"}'

# Update business profile fields
curl -X PATCH https://app.benchkey.com/api/v1/settings \
  -H "Authorization: Bearer bk_live_<tenantId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"business_profile": {"phone": "555-555-0200", "website": "https://riverfix.com"}}'

Node.js

// Update locale settings
const res = await fetch("https://app.benchkey.com/api/v1/settings", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer bk_live_<tenantId>_<secret>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    timezone: "America/Chicago",
    currency_code: "USD",
    default_tax_rate: 8.0,
    tax_apply_default: true,
    paper_size: "LETTER",
  }),
});
const settings = await res.json();
console.log(settings.timezone); // "America/Chicago"
console.log(settings.tax_rate); // 8

// Update business profile (merge, only supply changed fields)
const res2 = await fetch("https://app.benchkey.com/api/v1/settings", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer bk_live_<tenantId>_<secret>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    business_profile: {
      phone: "555-555-0200",
      tagline: "Fast, honest repairs.",
    },
  }),
});
const updated = await res2.json();
console.log(updated.business_profile.phone); // "555-555-0200"

Response

Returns the full updated settings object.

Error codes

Code	HTTP	Meaning
`invalid_body`	400	Request body is not a JSON object, or `business_profile` is not an object
`no_fields`	400	Body contained no keys
`invalid_field`	400	Key is not writable (e.g. `shop_name`), value has the wrong type or disallowed whitespace, `paper_size` is not `LETTER`/`A4`, `country_code` is not a valid ISO 3166-1 alpha-2 code, or `business_profile.<field>` is not writable
`currency_unsupported`	400	Currency is outside the supported list above
`unsupported_zero_decimal_currency_<CODE>`	400	A zero-decimal currency was supplied, for example `unsupported_zero_decimal_currency_JPY`
`settings_save_failed`	422	A setting write failed; earlier writes may have applied. Retrieve settings before retrying
`conflicting_country`	400	`country_code` and `business_profile.country` were both supplied but resolve to different countries
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	API key lacks `settings.read` or `settings.write` scope

System status

Settings

The settings object

business_profile fields

business_hours shape

Retrieve settings

curl

Node.js

Response

Update settings

Writable fields

Writable business_profile sub-fields

curl

Node.js

Response

Error codes

`business_profile` fields

`business_hours` shape

Writable `business_profile` sub-fields