Skip to content

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, currency or typesenseHost). 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. A N to set up badge means part of the home page's Finish setting up list belongs to that section, and the section's page lists those items at the top.
Section What is in it
Store and storefront Feature switches, SEO and redirects, legal entity, breadcrumbs, menus, media, collection listings, variants, taxonomy, events (whether ended events stay listed)
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
Shipping and labels Parcel labels: provider and its keys, label format and size, box sizes, return labels
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

Customer messaging has settings in two places. Customers and marketing holds marketing consent (what checkout and the sign-up forms ask, and whether sign-ups are confirmed by email), email campaigns (who they come from, where replies go, whether opens and clicks are tracked), contact requests and how long customer data is kept. Terms of sale and privacy notice, under Store and storefront, holds the legal pages and their version labels. What each one does is in Customer Messaging and Consent; the campaign settings and the sending domain are in Email Campaigns.

For a shop on a Badger Commerce plan, Plan & billing is the first tile: the plan, usage against its limits, plan changes, card and invoices. See Plan & billing; its "N to set up" badge counts the plan and launch items of the setup list.

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.

Plan limits

When your shop goes over a limit of its plan (products, locations, staff, table bookings a month and so on), a banner at the top of every admin page says what is over and what that means for your customers, with a link to Plan & billing to upgrade. Nothing in admin is ever blocked: you can keep adding products or staff, and only what shoppers see is held back (for example, the newest products beyond your plan's limit aren't live, and are marked Not live in the product list). The monthly customer limit only ever warns. The full list is in Plan Limits.

Site identity and time zone

Site identity (/admin/shopSettings/site-identity) holds the shop's own details rather than configuration keys: its name, logo, shop icon, default language, time zone and social accounts.

The shop icon is the small picture in the browser tab and the app icon a phone shows when a shopper adds your shop to its home screen. Choose a square image from the media gallery, at least 512 × 512 pixels; it is resized for each use, so one image covers both. Shops that named icon files by address in Settings keep them until an icon is chosen here, which replaces them. Icon HTML (favIconOverride, under Settings › Store) still takes priority over both. An MCP client sets the icon with manageBranding setIdentity iconUrl. Browsers see a new icon within a day.

The time zone list starts with the common zones (Europe/London first), then every zone A to Z. Dates and times in your shop, emails and event tickets use this zone: event start and end times, the ticket scanner's "today", point of sale day totals, promotion schedules and dates across the admin. Existing event times don't move when you change it; each event keeps the moment it was saved as, shown in the new zone.

A shop that hasn't chosen one uses the zone its language implies (English (UK) is Europe/London), and the page says so. A language that implies no single zone (English (US), for example) leaves the shop on Europe/London: the product editor's Event panel shows a warning until a zone is set. A zone that isn't in the list is refused and nothing is saved. A platform operator can set the same field on System › Tenants, and an MCP client with manageBranding setIdentity timeZone. The zone is carried by Site Data Transfer.

Site text

Site text (/admin/shopSettings/text) changes the platform's own wording for this shop: a footer line, a button label, an email subject. Each entry is a text key (for example footer.disclaimer, the first legal line in the footer, where a charity puts its charity and company numbers) and a language code (for example en). Saving a key the shop already overrides replaces its text; deleting it puts the platform's wording back. A key that no storefront text uses is refused, as is text containing script. The same changes can be made through MCP (siteText, manageSiteText; see MCP OAuth2).

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-askForZip jumps 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. It looks up the home page, pages (/p/), products (/product/), collections (/collection/) and categories (/c/), and shows a warning only when one of those isn't found; external URLs count as found, and any other path (search, the basket, a blog post) gets no mark

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. 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. siteConfig list takes search to find a setting by words in its key, name or description.