Opening Hours for POS Applications

POS applications are responsible for syncing location opening hours from the POS system to POS Hub. This guide explains how to keep location hours synchronized.

Responsibilities

As a POS application, you must:

1. Always set businessHours - This is required 100% of the time
2. Always set availability - Provide availability.delivery and availability.collection whenever your POS system tracks them

How to Sync Hours

You can sync location hours in two ways:

1. During Full Catalog Sync

Include location hours in your catalog import response:

{
  "location": {
    "businessHours": [
      {
        "weekday": "MONDAY",
        "timePeriods": [
          {
            "startTime": "09:00",
            "endTime": "22:00"
          }
        ]
      }
    ],
    "availability": {
      "delivery": [
        {
          "weekday": "MONDAY",
          "timePeriods": [
            {
              "startTime": "11:00",
              "endTime": "21:30"
            }
          ]
        }
      ],
      "collection": [
        {
          "weekday": "MONDAY",
          "timePeriods": [
            {
              "startTime": "10:00",
              "endTime": "21:00"
            }
          ]
        }
      ]
    }
  },
  "categories": [...],
  "products": [...]
}

2. Real-Time Updates via PATCH

For immediate updates, use the PATCH endpoint:

PATCH /v1/accounts/{accountId}/locations/{locationId}

Request Body:

{
  "businessHours": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    }
  ],
  "availability": {
    "delivery": [...],
    "collection": [...]
  }
}

Service Availability Structure

All hours use the ServiceAvailability structure:

{
  weekday: 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY' | 'SUNDAY'
  timePeriods: {
    startTime?: string      // 24-hour HH:MM format (e.g., "09:00")
    endTime?: string        // 24-hour HH:MM format (e.g., "22:00")
    startDate?: string      // YYYY-MM-DD format (optional)
    endDate?: string        // YYYY-MM-DD format (optional)
  }[]
}[]

Best Practices

• Always include businessHours in every sync
• Include availability.delivery and availability.collection when your POS system tracks them
• Use PATCH for real-time updates when hours change outside of catalog sync
• Ensure timezone is set correctly on the location
• Keep hours current - sync regularly

Related Documentation

• POS Integration Flow: End-to-end integration flow
• POS Prerequisites: Essential prerequisites