Modern Commerce: Admin Settings Reference
Modern Commerce settings live in two places that write to the same config store:
- Modern Commerce → Settings (
/local/moderncommerce/admin/settings.php): day-to-day store configuration. - Site administration → Plugins → Local plugins → Modern Commerce: Moodle's native pages for deeper configuration (webhook security, delivery channels, branding seeds, subscription defaults).
Changing a shared setting in either place updates the same value. Settings require Moodle site-config access (moodle/site:config) or the equivalent Modern Commerce capability.
- Store identity
- Currency
- Tax & documents
- Checkout fields
- Reviews & product form
- Navigation
- Notification display
- Payment gateways & webhook security
- Notification delivery (Slack/Teams)
- Branding
- Subscription settings
- Recommended setup order
Store identity
| Setting | Controls |
|---|---|
| Business name | Store name in receipts, support messaging, and summaries. Falls back to the site name. |
| Support email | Support mailbox shown in commerce messages. |
| Support URL | Optional buyer-facing help URL. |
Currency
Set this before creating production prices; it affects product cards, checkout, invoices, receipts, and reports.
| Setting | Controls |
|---|---|
| Primary currency | The single active store currency. Default USD. Chosen from 21 supported currencies (NGN, USD, EUR, GBP, ZAR, GHS, KES, UGX, TZS, XOF, XAF, EGP, MAD, CAD, AUD, INR, CNY, JPY, BRL, CHF, SGD). |
| Currency position | Symbol/code before or after the amount. Default before. |
| Decimal places | 0–6. Default 2. |
| Thousand separator | Default comma. |
| Decimal separator | Default period; cannot equal the thousand separator. |
Modern Commerce is single-currency: one active currency at a time, not simultaneous multi-currency. Changing it after orders exist makes reports harder to compare.
Tax & documents
| Setting | Controls |
|---|---|
| Tax mode | disabled (no site tax) or exclusive (tax added on top of price). |
| Default tax rate | Site-wide percentage, 0–100. |
| Invoice prefix | Invoice number prefix. Default INV. |
| Receipt prefix | Receipt number prefix. Default RCPT. |
Set document prefixes before your first production transaction.
Checkout fields
A master Collect contact information toggle (off by default) enables extra checkout fields: phone, address, city, state/province, country, ZIP/postal code. Each field is hidden, optional, or required. Keep fields hidden unless you have a real fulfilment, invoice, tax, or support reason to collect them.
Reviews & product form
| Setting | Controls |
|---|---|
| Enable reviews | Product/course review display and submission. Default on. |
| Show SKU field | Show SKU on product forms. Default off (SKUs auto-managed). |
| Show slug field | Show slug on product forms. Default off (slugs auto-generated). |
| Course detail sidebar position | Purchase sidebar on right (default) or left on desktop. |
Navigation
| Setting | Controls |
|---|---|
| Admin navigation label | Label for the manager/admin entry. |
| Learner navigation label | Label for learner-facing commerce navigation. |
| Hidden primary navigation items | Optionally hide Home, Dashboard, My courses, Site administration. |
| Cart position | Cart icon first (default) or last in the top-right user nav. |
Navigation and branding changes can be masked by theme caching. Purge Moodle caches if a change doesn't appear.
Notification display
| Setting | Controls |
|---|---|
| Notification position | Screen corner for toast messages. Default top-right. |
| Auto-dismiss delay | Milliseconds before a toast closes. Default 4000; 0 = stay until dismissed. |
This is on-screen toast behavior only: delivery channels are configured below.
Payment gateways & webhook security
Gateway credentials and gateway-specific webhook setup are managed at /local/moderncommerce/admin/gateways.php and /local/moderncommerce/admin/webhooks.php, not in a settings text field. Webhook security settings:
| Setting | Controls |
|---|---|
| Enable webhook IP whitelist | Webhook IP allow-listing where the gateway supports it. Default on. |
| Payment max retries | Retry attempts for payment workflows. Default 3 (0–10). |
Never place live gateway secrets in documentation, screenshots, or tickets. IP allow-listing supplements, but does not replace, signature verification. See Payments.
Notification delivery (Slack/Teams)
| Setting | Controls |
|---|---|
| Notification batch size | Queued records processed per batch. Default 100. |
| Slack enabled / webhook URL / signing secret | Slack delivery for operational notifications. |
| Teams enabled / webhook URL / signing secret | Microsoft Teams delivery for operational notifications. |
Keep webhook URLs and secrets private; rotate if exposed.
Branding
Branding seeds generate runtime CSS variables across admin, storefront, learner, and public pages: Primary, Secondary, Accent, Surface, Text, Link, Muted colors, base Radius, and an advanced Custom CSS field for small overrides. See Storefront.
Subscription settings
Under Site administration → Plugins → Local plugins → Modern Commerce → Subscriptions:
| Setting | Controls |
|---|---|
| Activation summary email | Send on activation. Default on. |
| Renewal digest email | Send renewal digests. Default on. |
| Reminder days | Days before expiry to remind. Default 7,3,1. |
| History retention days | Keep subscription history. Default 730. |
| Cleanup old subscriptions | Prune old records per retention. Default off. |
| Keep deleted user history | Keep history when a user is deleted. Default on. |
| Plan change cooldown | Days before another change. Default 30. |
| Allow lateral moves | Same-level plan moves. Default on. |
| Store downgrade credit | Credit on downgrade. Default on. |
| Cancel mode | immediate or end_of_period (default). |
| Allow user cancel | Self-service cancellation. Default on. |
| Enable trials | Trial behavior. Default on. |
| Trial auto convert | Auto-convert trials. Default off. |
Configure these before selling subscription products. See Subscriptions.
Recommended setup order
- Store identity.
- Currency (before creating prices).
- Tax (before opening checkout).
- Gateway credentials and webhooks.
- Checkout fields (only if needed).
- Document prefixes (before the first invoice/receipt).
- Navigation labels and cart position.
- Contact autoreply (test buyer + admin messages).
- Moodle core reCAPTCHA keys (if public forms are exposed).
- Course detail sidebar position.
- Notification delivery (Slack/Teams) if used.
- Subscription settings (before selling plans).
Configuration surfaces and access
ModernCommerce has two related settings surfaces:
/local/moderncommerce/admin/settings.phpis the day-to-day React configuration app for identity, currency, tax, checkout, navigation, notification display, reviews, product-form fields, and contact email behavior. It requires the applicable ModernCommerce settings capability at system context.- Site administration → Plugins → Local plugins → Modern Commerce contains native Moodle settings for gateway/webhook security, notification delivery channels, branding seeds, navigation hooks, and subscription defaults. These settings normally require
moodle/site:config.
Do not grant broad Moodle site configuration merely to let a staff member update a narrow commerce setting. Use the ModernCommerce role presets or a tested custom system role where the React settings service supports the required operation.
Core reCAPTCHA prerequisite
ModernCommerce does not store separate Google keys. Public support and newsletter forms read Moodle's global reCAPTCHA public and private keys. Configure both keys in Moodle administration before opening those forms on production, then verify the browser submits g-recaptcha-response and the server can reach Google's verification endpoint.
After changing settings
- Save and reload the administration surface to confirm the normalized value.
- Purge Moodle caches after navigation, branding, webhook, or service-definition changes.
- Test currency/tax changes with a new sandbox order; never reinterpret historical orders using a new currency.
- Test checkout field requirements as a buyer, including validation failures.
- Send test email after identity, support, branding, SMTP, or template changes.
- Send a signed provider test webhook after gateway or webhook-security changes.
- Test public pages on desktop/mobile and as a user without management capabilities.
Developer source of truth
The React settings app persists through the commerce settings service; native settings are declared in settings.php; labels and descriptions come from language strings. Add a setting to its owning service/schema, validate it server-side, enforce context and capability checks, expose it through the intended administration surface, document its default and operational impact, and add an upgrade/default path when existing installations require one.