Opening Hour Groups

An opening_hour_group is a collection of opening hours. Each opening hour specifies a week_day (e.g., Sunday, Monday, Tuesday, etc.) and an array of intervals. Each interval is represented in the format {starts_at: HH:MM, ends_at: HH:MM} using a 24-hour time format.

🕦

Intervals

These are non-overlapping periods within a day when a branch is open. If the starts_at time is greater than or equal to the ends_at time, the interval spans over two days, breaking the 24-hour cycle. For example, {starts_at: 10:00, ends_at: 06:00} on Tuesday means the branch is open from Tuesday at 10:00 AM until Wednesday at 6:00 AM.

Example of Opening Hour Groups

• Example:
  JSON

  "opening_hour_group": {
  "id": 1,
  "start_date": "2023-02-06", // for special timings only
  "end_date": "2023-02-06", // for special timings only
  "is_special_timing": true, // determines wether the opening_hour_group is a special timing or a default hours
  "is_force_closed": false, // force closure disables the effect of the opening_hour_group
  "opening_hours": [
  		{
  		"id": 1,
  		"week_day": "monday",
  		"intervals":[
  				{
  				"starts_at": "9:00",
  				"ends_at": "17:00"
  				},
  				{
  				"starts_at": "19:00",
  				"ends_at": "23:00"
  				}
  			]
  		},
  		{
  		"id": 1,
  		"week_day": "tuesday",
  		"intervals":[
  				{
  				"starts_at": "10:00",
  				"ends_at": "06:00"
  				}
  			]
  		}
  	]
  }

  • Monday:
    • Intervals: {starts_at: 09:00, ends_at: 17:00}, {starts_at: 19:00, ends_at: 23:00}
  • Tuesday:
    • Intervals: {starts_at: 10:00, ends_at: 06:00} (This means open from Tuesday 10:00 AM to Wednesday 6:00 AM)
  • Remaining Days:
    • Any other day that is not mentioned in the opening_hour_group is considered closed.

📘

No Overlapping

An opening_hour_group contains a unique set of days, meaning no opening_hour_group will contain more than one opening_hour for the same week_day. Additionally, opening_hour intervals do not overlap.

Default Hours VS Special Timings

Default Opening Hours

• Definition: Default opening hours are specific to a single branch. They define the standard operating times applied to the branch unless a special timing is in effect.
• Main Features:
  • Unique: Each branch has its own unique default opening hour group.
  • Mandatory: These hours must be set for each branch.

Special Timings

• Definition: Special timings are exceptional operating hours that apply during a specific period, such as official holidays or special events. These timings can be shared across multiple branches.
• Main Features:
  • Many-to-Many Relationship: A special timing can be linked to multiple branches through the branch_special_timings table.
  • Specific Interval: Special timings have a start and end date and these dates do not overlap with each other, meaning that you cannot assign two overlapping special timings to the same branch

    🕑

    Start Date / End Date

    Special Timings starts taking action at start_date, 00:00 date-time and stops working at end_date 00:00 date-time. All relative to the brand_branch's current timezone.

  • Examples: Ramadan hours, Christmas hours, etc.

Differences Between Default and Special Timings

• Default Opening Hours are the standard set hours for a branch and are unique to it.
• Special Timings can apply to multiple branches and override default hours during specified dates (start_date and end_date).

How to Calculate Entity Status

Opening Hour Groups are relative to the assignee's timezone, meaning that if a branch is open from 9 to 5, it is open relative to its local time and not any other timezone or UTC.

Branch Timezone

• Timezone Consideration: All working hours are affected by the timezone of the branch to which they are assigned. It is essential to convert and compare times relative to the branch's timezone to accurately determine its open/closed status.

Calculating Status

1. Current Time and Timezone: Determine the current time in the branch’s timezone.
2. Compare with Intervals: Check if the current time falls within any of the active intervals for that day.
3. Priority of Timings: If a special timing is active for the current date, it takes precedence over default opening hours, and the default opening hours are ignored.
4. Missing Days: If a day does not exist in the opening_hour_group, it automatically means that its closed.

Example of Status Calculation

• Branch Timezone: EST (Eastern Standard Time)
• Current Time: Tuesday, 8:00 AM EST
• Default Hours:
  • Tuesday: {starts_at: 10:00, ends_at: 16:00}
• Special Timing:
  • Tuesday: {starts_at: 08:00, ends_at: 18:00} on December 25

If today is December 25 and the current time is 8:00 AM, the branch is open due to the Christmas special timing.
If any other day, the branch is considered closed since it opens at 10:00 AM according to the default hours.