Online Settings

Overview

Online Settings is the location-specific configuration page for the online ordering channel. It controls critical operational parameters including order capacity management (how many orders and items are accepted per time slot), delivery and pickup day availability, tip collection settings, checkout note options, and menu assignments. Each location has its own independent online settings stored on the Location document, allowing multi-location businesses to tailor their online ordering experience per venue.

The settings are distinct from the OnlineOrderingService -- while that service handles the broader online ordering feature setup, OnlineSettingsService specifically manages the operational parameters that govern how online ordering functions day-to-day at each location.

Purpose

This page lets you configure how your online ordering channel operates for a specific location, including order capacity limits, available delivery and pickup days, tip collection preferences, checkout notes, and which menus are displayed to online customers.

Key Concepts

• Order Capacity: A comprehensive system for controlling order volume per time slot. The base configuration includes time_slot_duration_min (the interval in minutes), limit_orders_per_time_slot (boolean toggle), number_of_orders_per_time_slot (maximum orders), limit_items_per_time_slot (boolean toggle), and number_of_items_per_time_slot (maximum items). These global settings apply by default to all time slots unless overridden by time-specific rules.
• Flexible Capacity: An advanced capacity mode that allows exceeding the base order limit when order value meets a threshold. Enabled via enable_flexible_limit_order_per_time_slot, configured with value_threshold_per_time_slot (minimum order value to qualify) and allow_up_to (number of extra orders allowed). This allows high-value orders to be accepted even when the standard order limit is reached.
• Time-Specific Rules: Named override rules that replace the global capacity settings during defined time windows on specific days. Each rule has a unique name, a time_range (with from and to times), an active_days array (days of the week from Sunday to Saturday), and its own number_of_orders_per_time_slot, number_of_items_per_time_slot, optional flexible capacity settings, and optional category-specific limits. The hasOverlappingTimeRanges validation from the SchedulingTrait ensures no two rules overlap on the same day.
• Menu Assignment: Online settings define a default_menu_id (the primary menu always displayed) and optional extra_menu_ids (additional menus with schedule-based availability). Extra menus have their own schedule per location and are validated for uniqueness, non-duplication with the default, and non-overlapping schedules via the isScheduleOverlap method.
• Collect Tips: A configurable tipping system stored as an object with enabled (boolean), options (array of up to 3 percentage values between 1-100, e.g., [10, 15, 20]), and calculate_tips (a CalculateTipsOptions enum value controlling whether tips are calculated before or after taxes).

Route

• Backoffice Route: /online-settings
• Backend Controller: app/Http/Controllers/Api/BackOffice/OnlineSettingsController.php
• Service: app/Services/BackOffice/OnlineSettingsService.php
• Request Validator: app/Http/Requests/BackOffice/OnlineSettings/StoreOnlineSettingsRequest.php
• Resource: app/Http/Resources/BackOffice/OnlineSettings/ShowOnlineSettingsResource.php
• Constants: app/Constants.php -- getDefaultOnlineSettings() method
• Vue Component: src/views/online-settings/OnlineSettingsForm.vue
• Store Module: src/store/modules/onlineSettings.ts
• Related Components: src/views/in-house/components/forms/OrderCapacityManagement.vue, src/views/in-house/components/forms/CollectTips.vue, src/views/in-house/components/forms/CheckoutNotes.vue, src/components/DefaultMenusSection.vue

Actions

View Online Settings

Retrieve the current online settings for a specific location. The service resolves the Location document, reads its online_settings, and enriches it by fetching the full Menu objects for both the default menu and extra menus (including their names, descriptions, and schedules). The resource transforms the response by stripping raw default_menu_id and extra_menu_ids and replacing them with expanded menu objects. Category names are also resolved for any category-specific order limits via alsoRetrieveCategoryName: true.

• Endpoint: GET /api/back-office/online-settings/{locationId}
• Response: JSON ShowOnlineSettingsResource containing order capacity settings, delivery/pickup available days, collect_tips config, allow_notes config, default_menu (with id, name, description, schedule), and extra_menus array

Update Online Settings

Save updated online settings for a specific location. The request is validated through StoreOnlineSettingsRequest which merges defaults from Constants::getDefaultOnlineSettings() for order_capacity, collect_tips, and allow_notes before validation. The service performs additional business logic validation:

1. Validates the default menu is eligible via isMenuEligible
2. For each extra menu: verifies it is not the same as the default menu, validates its eligibility, checks its schedule for self-overlap via isSingleScheduleOverlap, checks for duplicate extra menus, and validates schedule non-overlap between all extra menu pairs via isScheduleOverlap
3. Saves the validated settings to the location's online_settings field
4. Dispatches a ReloadMenu event to refresh cached menus for the location

• Endpoint: PUT /api/back-office/online-settings/{locationId}
• Request Body: Full settings object (see Fields section)
• Response: Success response

Fields

Order Capacity - Global Settings

Field	ID	Type	Required	Validation
Time Slot Duration (min)	order_capacity.time_slot_duration_min	Number	Yes	required|numeric|gt:0
Limit Orders per Slot	order_capacity.limit_orders_per_time_slot	Boolean	Yes	required|boolean
Max Orders per Slot	order_capacity.number_of_orders_per_time_slot	Number	Conditional	Required and numeric|gt:0 when limit_orders is true
Limit Items per Slot	order_capacity.limit_items_per_time_slot	Boolean	Yes	required|boolean
Max Items per Slot	order_capacity.number_of_items_per_time_slot	Number	Conditional	Required and numeric|gt:0 when limit_items is true

Order Capacity - Flexible Capacity

Field	ID	Type	Required	Validation
Enable Flexible Capacity	order_capacity.enable_flexible_limit_order_per_time_slot	Boolean	Yes	required|boolean
Value Threshold per Slot	order_capacity.value_threshold_per_time_slot	Number	Conditional	Required and numeric|gt:0 when flexible enabled
Allow Up To (extra orders)	order_capacity.allow_up_to	Integer	Conditional	Required and integer|gt:0 when flexible enabled

Order Capacity - Category-Specific Limits

Field	ID	Type	Required	Validation
Enable Category Limits	order_capacity.enable_limit_specific_categories	Boolean	Yes	required|boolean
Category Limits	order_capacity.limit_specific_categories	Array	Conditional	Required when category limits enabled
Category ID	limit_specific_categories.*.category_id	String	Yes	required|distinct -- must exist in settings collection
Items per Slot per Category	limit_specific_categories.*.number_of_items_per_time_slot	Number	Yes	required|numeric|gt:0

Order Capacity - Time-Specific Rules

Field	ID	Type	Required	Validation
Rule Name	time_specific_rules.*.name	String	Yes	required|string|distinct -- unique among rules
Time Range From	time_specific_rules.*.time_range.from	String	Yes	required|string
Time Range To	time_specific_rules.*.time_range.to	String	Yes	required|string
Active Days	time_specific_rules.*.active_days	Array	Yes	Day names: Sunday through Saturday
Orders per Slot	time_specific_rules.*.number_of_orders_per_time_slot	Number	Yes	required|numeric|gt:0
Items per Slot	time_specific_rules.*.number_of_items_per_time_slot	Number	Yes	required|numeric|gt:0
Enable Flexible (per rule)	time_specific_rules.*.enable_flexible_limit_order_per_time_slot	Boolean	No	nullable|boolean
Category Limits (per rule)	time_specific_rules.*.limit_specific_categories	Array	No	Same structure as global category limits

Delivery and Pickup

Field	ID	Type	Required	Validation
Delivery Available Days	delivery_available_days	Array	No	Day names: Sunday through Saturday
Pickup Available Days	pickup_available_days	Array	No	Day names: Sunday through Saturday

Tips

Field	ID	Type	Required	Validation
Enable Tips	collect_tips.enabled	Boolean	Yes	required|boolean
Tip Options	collect_tips.options	Array	Conditional	Required when tips enabled; up to 3 values, each numeric|min:1|max:100
Calculate Tips Method	collect_tips.calculate_tips	Enum	Conditional	Required when tips enabled; CalculateTipsOptions enum value

Notes

Field	ID	Type	Required	Validation
Enable Notes	allow_notes.enabled	Boolean	Yes	required|boolean
Notes Placeholder	allow_notes.placeholder	String	Conditional	Required when notes enabled; string

Menu Assignment

Field	ID	Type	Required	Validation
Default Menu ID	default_menu_id	String	Yes	required|string -- must be an eligible menu
Extra Menu IDs	extra_menu_ids	Array	No	Array of menu ID strings; each must be unique and not match default

Business Rules

• The default menu must pass eligibility validation via isMenuEligible from the MenuTrait, ensuring it is a valid, active menu that can serve the online ordering channel.
• Extra menus cannot be the same as the default menu. The service checks $extraMenuId === $settings['default_menu_id'] and aborts with a 400 error and message "Extra menu cannot be the same as default menu" if they match.
• Extra menus cannot be duplicated. The service uses a nested loop comparing $extraMenuId === $extraMenuId2 (skipping self-comparison) and aborts with "Extra menu cannot be duplicated" if a duplicate is found.
• Extra menu schedules must not overlap with each other. The service calls isScheduleOverlap for each pair of extra menus, passing their schedules resolved via getSchedule($location). A descriptive error naming both conflicting menus is returned: "There is a schedule overlap between :extraMenuName and :extraMenu2Name".
• Each extra menu's schedule is also checked for internal self-overlap via isSingleScheduleOverlap, returning "There is a time overlap in the schedule" if the menu's own time windows conflict.
• Time-specific rules within order capacity must not have overlapping time ranges for the same day. The hasOverlappingTimeRanges validation (from SchedulingTrait) is applied as a custom validation closure on the time_specific_rules array.
• The StoreOnlineSettingsRequest merges default values from Constants::getDefaultOnlineSettings() before validation, ensuring that optional fields have sensible defaults. Defaults include all seven days for delivery and pickup, tips disabled with [10, 15, 20] options and AFTER_TAXES calculation, and notes disabled with a placeholder text.
• Conditional validation rules are dynamically computed: number_of_orders_per_time_slot is required only when limit_orders_per_time_slot is true; flexible capacity fields are required only when enable_flexible_limit_order_per_time_slot is true; tip options are required only when collect_tips.enabled is true; and notes placeholder is required only when allow_notes.enabled is true.

Customer Impact

• Online Ordering: These settings directly control every aspect of the customer's online ordering experience at the location. Order capacity limits prevent order overload during peak hours. Delivery and pickup day settings determine when customers can place orders. Tip options appear at checkout. Notes allow special instructions.
• Delivery: The delivery_available_days array controls which days delivery is offered. Defaults to all seven days (Sunday through Saturday). Removing a day prevents customers from selecting delivery for that day.
• Pickup: The pickup_available_days array controls which days pickup is available. Functions the same as delivery availability. Defaults to all seven days.
• Kitchen Operations: Order capacity limits directly control the maximum workload the kitchen receives per time slot. Flexible capacity allows merchants to accept additional high-value orders without overwhelming normal capacity. Category-specific limits can protect slow-prep items from being over-ordered.
• Revenue: Tip collection settings directly affect revenue. The calculation method (before or after taxes) impacts the suggested tip amounts shown to customers.

FAQs

What are the default online settings for a new location?

New locations use defaults from Constants::getDefaultOnlineSettings(): all seven days available for both delivery and pickup, tips disabled with 10%/15%/20% option presets calculated after taxes, notes disabled with a sample placeholder text, no default menu assigned, and empty extra menus. Order capacity settings must be configured manually.

How do time-specific rules work?

Time-specific rules override the global order capacity settings during their defined time windows on their specified active days. For example, you can create a "Lunch Rush" rule for 11:00-14:00 on weekdays with a higher order limit, and a "Dinner" rule for 17:00-21:00 with different limits. Rule names must be unique, and time ranges must not overlap for the same day. Each rule can also have its own flexible capacity and category-specific limits.

Can I have different online settings per location?

Yes. Online settings are stored on each Location document independently. Each location can have completely different order capacity limits, available days, tip settings, menu assignments, and all other configurations. Changes to one location do not affect others.

What is flexible capacity?

Flexible capacity allows exceeding the base order limit when the total order value meets a minimum threshold. For example, if the limit is 10 orders per slot and flexible capacity is enabled with a threshold of 50 and "allow up to" 5, then up to 5 additional orders can be accepted if each meets the value threshold. This is useful for not turning away high-value orders during busy periods.

How do extra menus with schedules work?

The default menu is always available during operating hours. Extra menus have their own schedules (configured on the menu itself, resolved per location) and are only shown during their configured time windows. This allows offering different menus for breakfast, lunch, and dinner on the online ordering channel. Schedules across extra menus must not overlap with each other.

What does the "calculate tips" option control?

The calculate_tips field determines how suggested tip amounts are calculated: either before taxes (on the subtotal) or after taxes (on the total including tax). The CalculateTipsOptions enum defines the valid values. This affects the dollar amounts shown to customers when they select a tip percentage at checkout.

Troubleshooting

"Extra menu cannot be the same as default menu" error

You have added the same menu as both the default and an extra menu. Remove the duplicate from the extra menus list, or choose a different menu as the default. The service compares IDs directly.

"There is a schedule overlap between X and Y" error

Two extra menus have overlapping availability schedules at the current location. The error message names both conflicting menus. Review their schedules (configured on each menu, resolved per location via getSchedule) and adjust time windows so they do not conflict.

"There is a time overlap in the schedule" error for an extra menu

A single extra menu has overlapping time ranges within its own schedule at this location. The isSingleScheduleOverlap check found conflicting time windows. Review and fix the menu's schedule configuration.

Order capacity limits are not being enforced

Verify that limit_orders_per_time_slot or limit_items_per_time_slot is set to true and the corresponding numeric value is greater than zero. Check that time_slot_duration_min is configured with a sensible value. If using time-specific rules, verify the rule's active days and time range cover the period in question. The OrderCapacityService reads these settings from the location's online_settings at order time.

Time-specific rules validation fails

Ensure each time-specific rule has: a unique name (enforced by distinct validation), valid time_range.from and time_range.to strings, at least one valid active_days entry (full day names like "Monday"), and positive numeric values for both number_of_orders_per_time_slot and number_of_items_per_time_slot. If flexible capacity is enabled per rule, value_threshold_per_time_slot and allow_up_to must also be provided.

Saved settings do not appear on the online ordering frontend

After saving, a ReloadMenu event is dispatched. If changes still do not appear, verify the menu cache has been refreshed for the location. Check that the default menu is correctly assigned and that its display groups have Online Ordering in their visibility arrays.

Technical Details

Default Settings Initialization

The Constants::getDefaultOnlineSettings() method returns the default online settings structure:

• order_capacity: Uses $DEFAULT_ORDER_CAPACITY_SETTINGS static property
• delivery_available_days: All seven days (Sunday through Saturday)
• pickup_available_days: All seven days (Sunday through Saturday)
• collect_tips: {enabled: false, options: [10, 15, 20], calculate_tips: "after_taxes"}
• allow_notes: {enabled: false, placeholder: "E.g. 'For Oliver' or 'I'm allergic to mushrooms'"}
• default_menu_id: null
• extra_menu_ids: empty array

The StoreOnlineSettingsRequest.prepareForValidation() method merges these defaults with the incoming request data before validation, ensuring omitted fields receive sensible defaults rather than null values.

Backoffice Store Module

The Vue store module (src/store/modules/onlineSettings.ts) transforms the API response into a form-friendly structure. It maps collect_tips.options (array of 3 values) to individual tip_percentage_1, tip_percentage_2, tip_percentage_3 fields. It maps collect_tips.enabled to is_collect_tips and allow_notes.enabled to is_allow_notes. Menu assignment is transformed into a unified menus array where each entry has is_default (boolean) and data (menu object). The saveOnlineSettingsForm action reverses these transformations before sending to the API.

Schedule Overlap Detection

The SchedulingTrait provides three validation methods used during online settings update:

• isMenuEligible($menuId): Validates that a menu exists, is active, and can serve the online ordering channel
• isSingleScheduleOverlap($schedule): Checks if a single menu's schedule has internal time-range conflicts
• isScheduleOverlap($schedule1, $schedule2): Compares two menu schedules for cross-menu time-range conflicts

Assistant Guidance

When users ask about online settings, first determine which aspect they need help with: order capacity, delivery/pickup days, tips, notes, or menu assignment. For order capacity questions, explain the three-tier hierarchy: global settings apply by default, time-specific rules override during their configured periods, and flexible capacity provides value-based exceptions. Emphasize that online settings are per-location and changes only affect the selected location. If users report issues with menu display in online ordering, check both the online settings menu assignment and the individual display group visibility settings. For tip configuration, explain the difference between calculating tips before versus after taxes and how the three percentage options appear at customer checkout.

Relations

Depends On

• Locations: Online settings are stored on the Location document's online_settings field. A valid location must exist.
• Menus: Default and extra menus must exist and pass eligibility checks. Menu schedules are resolved per location for overlap validation.
• Categories: Category-specific order limits reference category IDs that must exist in the settings collection.
• Constants: Default values are sourced from Constants::getDefaultOnlineSettings().
• SchedulingTrait: Provides isScheduleOverlap, isSingleScheduleOverlap, and hasOverlappingTimeRanges validation methods.
• MenuTrait: Provides isMenuEligible and getEligibleMenu methods for menu validation.

Affects

• Online Ordering Channel: Directly controls order capacity, available days, tip options, note collection, and menu display for the customer-facing online ordering experience.
• Order Processing: Order capacity limits (managed by OrderCapacityService) determine whether new orders are accepted or rejected during specific time slots.
• Menu Cache: Updating online settings dispatches a ReloadMenu event, triggering a refresh of cached menus for the affected location.
• Kitchen Operations: Order and item limits per time slot directly impact kitchen workload, order throughput, and preparation scheduling.
• Transaction Processing: Tip settings influence the TransactionService by determining how tip amounts are calculated and applied to orders.
• Revenue: Tip collection settings and calculation method directly affect the tip revenue collected per order.