Settings¶
Settings (/admin/settings) is where a site administrator configures a shop: checkout behaviour, emails, search, Gift Aid, integrations and so on. It replaces the old "Configuration (New)" and "Configuration (Old)" pages. Both old addresses still work and send you to the right place.
Access needs the ADMIN or SUPERADMIN role.
Finding a setting¶
The Settings home page has two ways in:
- Search box. Type any part of a setting's name, its description or its key (for example
gift aid,currencyortypesenseHost). Results show where the setting lives; pick one and the page opens with that setting highlighted. - Section tiles. Settings are grouped into sections, each showing how many settings it holds and how many you have changed from the default.
| Section | What is in it |
|---|---|
| Store and storefront | Feature switches, SEO and redirects, legal entity, breadcrumbs, menus, media, collection listings, variants, taxonomy |
| Checkout and payments | Basket, checkout flow, currency and payment options, point of sale |
| Orders and email | Email branding and delivery, order confirmation, cancellation and return emails, customer returns |
| Subscriptions | Billing day, subscription emails, failed payment follow-up |
| Fundraising and Gift Aid | Fundraiser defaults and the HMRC Gift Aid connection |
| Search | Search engine connection, indexing, facets, search tracking |
| AI and integrations | AI provider and model, Slack, file storage, reporting, design brief data |
| Security and access | Sign-in, bot protection, reCAPTCHA, plan entitlements |
| Advanced | Admin dashboard options, any setting not listed elsewhere, and the raw configuration store |
Under the tiles, Other settings links to pages that manage their own data: Site identity, Payment providers, Theme, Design brief, Custom CSS, Custom domains, Navigation menu, Site text, Pipelines and Platform upgrades.
Editing a section¶
Each section is one page. A list of the section's groups runs down the left (a row of chips on a phone) and follows you as you scroll. Every group is a card of settings.
- Each setting shows a Default or Customised badge. When customised, the default is shown beside it.
- Change as many settings as you like, across groups. A bar at the bottom shows how many changes are waiting. Save changes saves them all together; Discard puts them back.
- If any value is invalid (a number that is not a number, a colour that is not
#RRGGBB, a redirect rule with no target) nothing is saved and the problem is shown under that setting. - Reset to default on a setting removes your override immediately, after a confirmation.
- The box at the top filters the settings in the section as you type.
?q=in the address pre-fills it. - A link such as
/admin/settings/checkout#setting-askForZipjumps straight to one setting.
Kinds of setting¶
| Looks like | Used for |
|---|---|
| Switch | On/off settings |
| Text, number | Plain values. Greyed text shows the default |
| Multi-line box | Long text such as return instructions or the humans.txt entry |
| Drop-down | A fixed set of choices |
| Colour swatch and hex box | Email brand colours |
| Collection picker | Settings that hold a list of collections |
| List editor | Lists of values, for example mandatory address fields |
| Redirect rules table | URL redirects with 301/302 codes, reordering and a live "does the target exist" check |
Secrets¶
API keys, tokens and passwords are never shown, not even to administrators. A secret setting shows Set or Not set. To change it, type the new value; leave the box empty to keep the current one. Remove saved value deletes it.
Test buttons¶
- Orders and email → Email branding: send a sample email to any address to preview your branding. Save first.
- Fundraising and Gift Aid → Gift Aid: test the HMRC connection with the saved credentials, without submitting a claim. Save first.
Advanced¶
/admin/settings/advanced holds the Advanced section's guided settings and three raw tools:
- Stored values: every value saved for the site, including keys that have no guided setting. Edit, delete or add a key. Editing here skips validation, so prefer the guided setting when there is one. Secret values are withheld. Download JSON exports the site's editable values (secrets are exported without their values).
- Site context: how the platform currently sees the site (read only), useful for diagnosing a problem.
For developers¶
New configuration keys must be mapped to a section and given titles; see the Site-Specific Configuration notes in CLAUDE.md. The mapping lives in SettingsSections; a unit test fails if a group is missing, and a group that is somehow unmapped still appears under Advanced so a setting is never unreachable.
Settings can also be read and changed through the MCP siteConfig and manageSiteConfig tools.