Settings Module — Storefront

HTTP surface for the storefront to read public, platform-wide settings (branding, contact details, currency hints, store toggles, etc.). The whole storefront-public configuration is keyed by a registry that flags each setting as either public: true (exposed here) or admin-only (never exposed here, regardless of group).

Source: api-modules/settings/src/controllers/store-settings.controller.ts.

Admin and vendor settings (key registration, scoped overrides, secrets) live in sibling docs.

Conventions

Authentication

There is no auth on this surface — the only safety is the registry's public flag. Keys without that flag are never exposed here. Unknown groups and keys deliberately return 404 rather than empty payloads so an attacker can't probe for the existence of admin-only configuration.

Response envelope

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200
}

Error envelope

Domain types

ScopeSettingsResponse

/** Full-scope response — nested by group, with unknown-typed values. */
type ScopeSettingsResponse = Record<string, Record<string, unknown>>;

GroupSettingsResponse

/** Single-group response — flat key→value. */
type GroupSettingsResponse = Record<string, unknown>;

SettingValueResponse

/** Single-key response — uniform { value } wrapper regardless of underlying type. */
type SettingValueResponse = { value: unknown };

Consumers narrow on known keys at the call site; the response surface keeps unknown because typing every key would drift as the registry evolves.

Endpoints

GET /store/settings — All public settings

Returns the entire public storefront configuration as { <group>: { <key>: <value> } }. Use this for the initial app bootstrap so the storefront has a consistent snapshot of branding, currency, etc. Admin-only keys are filtered out at the service layer.

Response 200

{
  "data": {
    "branding": {
      "logo_url": "https://cdn.example/logo.png",
      "store_name": "Example Shop"
    },
    "contact": {
      "support_email": "help@example.com",
      "support_phone": "+91 90000 00000"
    }
  },
  "message": "Success",
  "statusCode": 200
}

GET /store/settings/:group — Public settings for one group

Returns the flat { <key>: <value> } map for a single group. The whole group must contain at least one public key — a group whose keys are all admin-only returns 404.

Path params

Response 200

{
  "data": {
    "logo_url": "https://cdn.example/logo.png",
    "store_name": "Example Shop"
  },
  "message": "Success",
  "statusCode": 200
}

Errors

GET /store/settings/:group/:key — Single public setting

Returns { value: <unknown> } for a single key.

Path params

Response 200

{
  "data": { "value": "https://cdn.example/logo.png" },
  "message": "Success",
  "statusCode": 200
}

Errors

Related modules

• Admin / vendor settings surfaces — share the same underlying SettingsService, but expose admin- and vendor-scoped registry keys. See docs/separated/admin/settings.md and docs/separated/vendor/settings.md.