Settings Module Documentation¶

Overview¶

The Settings module manages application-wide configuration settings stored as key-value pairs. It supports dynamic settings for features like delivery thresholds, pickup messages, and contact information.

Data Model¶

Setting Entity¶

File: backend/src/modules/settings/models/setting.ts

Field	Type	Required	Default	Description
key	string	Yes	-	Primary key, unique setting identifier
value	string	No	null	Setting value (can be null)

Valid Setting Keys¶

The following setting keys are used in the application:

Key	Value Type	Description	Example
free_delivery_threshold	number (string)	Minimum order amount for free delivery in BHD (cents)	"1000" (10 BHD)
pickup_message	text	Message displayed for pickup orders	"Your order will be ready in 30 minutes"
ceo_whatsapp	string	CEO's WhatsApp number for customer support	"+97312345678"

Note: Values are stored as strings in the database. Numbers should be stored as string representations (e.g., "1000" for 1000 cents = 10 BHD).

Service Methods¶

SettingsModuleService¶

File: backend/src/modules/settings/service.ts

The service extends MedusaService which automatically provides standard CRUD methods: - listSettings(filters, options) - List settings with optional filters - createSettings(data) - Create a new setting - updateSettings(id, data) - Update an existing setting - deleteSetting(id) - Delete a setting

Custom Methods¶

getAllSettings()¶

Returns all settings as a typed flat object (key-value pairs).

async getAllSettings(): Promise<Record<string, string | null>>

Returns: Object with setting keys as properties and their values.

Example:

const settings = await settingsModuleService.getAllSettings()
// Returns: {
//   free_delivery_threshold: "1000",
//   pickup_message: "Your order will be ready in 30 minutes",
//   ceo_whatsapp: "+97312345678"
// }

getSettingByKey(key)¶

Retrieves a single setting by its key.

async getSettingByKey(key: string): Promise<Setting | null>

Parameters: - key - The setting key to retrieve

Returns: Setting object or null if not found.

Example:

const threshold = await settingsModuleService.getSettingByKey("free_delivery_threshold")
// Returns: { key: "free_delivery_threshold", value: "1000" }

upsertSetting(key, value)¶

Creates or updates a setting.

async upsertSetting(key: string, value: string | null): Promise<Setting>

Parameters: - key - The setting key - value - The setting value (can be null)

Returns: The created or updated setting.

Example:

const setting = await settingsModuleService.upsertSetting("free_delivery_threshold", "1500")

upsertManySettings(settings)¶

Bulk creates or updates multiple settings.

async upsertManySettings(settings: Record<string, string | null>): Promise<Setting[]>

Parameters: - settings - Object with setting keys as properties and their values

Returns: Array of created/updated settings.

Example:

const results = await settingsModuleService.upsertManySettings({
  free_delivery_threshold: "1000",
  pickup_message: "Ready in 30 minutes",
  ceo_whatsapp: "+97312345678",
})

Usage Examples¶

Getting All Settings¶

const settings = await settingsModuleService.getAllSettings()
const threshold = parseInt(settings.free_delivery_threshold || "0", 10)

Updating a Single Setting¶

await settingsModuleService.upsertSetting("free_delivery_threshold", "2000")

Bulk Updating Settings¶

await settingsModuleService.upsertManySettings({
  free_delivery_threshold: "1500",
  pickup_message: "New pickup message",
  ceo_whatsapp: "+97387654321",
})

Checking if Free Delivery Applies¶

const settings = await settingsModuleService.getAllSettings()
const threshold = parseInt(settings.free_delivery_threshold || "0", 10)
const cartTotal = 1200 // in cents (12 BHD)

if (cartTotal >= threshold) {
  console.log("Free delivery applies!")
}

Module Registration¶

The module is registered in medusa-config.ts:

modules: [
  {
    resolve: "./src/modules/settings",
  },
]

Migration¶

Generate and run migrations:

npx medusa db:generate settings
npx medusa db:migrate

This creates the setting table in PostgreSQL with key as primary key and value column.

API Routes¶

The module is exposed via custom API routes: - GET /store/settings - Returns all settings as a flat object - GET /admin/settings - List all settings (admin) - PATCH /admin/settings - Bulk upsert settings (admin)

See STORE_ENDPOINTS.md and ADMIN_ENDPOINTS.md for API details.

Adding New Settings¶

To add a new setting:

Choose a unique key name (snake_case recommended)
Determine the value type and format
Add documentation to this file
Use upsertSetting or upsertManySettings to create it

Example:

await settingsModuleService.upsertSetting("store_phone", "+97312345678")