Structuring Availability in Feeds

Choosing An Availability Format

There are two ways to specify availability data: (1) Spots Open or (2) Recurrence. Choose only one method to use across all your merchants and services. Once you select a method, you must stick with it for the entire integration (feeds, booking server, and real time updates).

Use the following guide to help you determine which availability format is more suitable:

  • In your system, do you store availability as explicit slots, for example, 8:00 AM - 8:30 AM?
  • In your system, do you store availability in a recurring format, meaning merchants have services that occur with consistent frequency with few deviations? For example, slots repeat every 15 minutes from 9:00 AM - 5:00 PM, and only one seat is available in each 15 minute increment.
  • For your merchants’ services, can there be more than one open spot at a time? For example, 30 open spots for a class
  • None of the above apply?
    • Use Spots Open
    • Note: While using recurrence is more efficient and can result in smaller feed sizes, if your data model does not natively support recurrence, it is not recommended to use recurrence, as you will need to recalculate the entire day's worth of recurring slots for every realtime update.

    Spots Open

    Parameter Definitions:

    • spots_open: The number of spots currently available for this availability entry.
    • spots_total: The total number of spots that the merchant has for this configuration, including those that are not available.

    The Spots Open method explicitly indicates every slot availability and supports the model of having multiple spots for the same service. These two parameters work together to build a digital representation of the service capacity.

    When a booking happens, the number of spots_open should decrement by 1 through a realtime update (the number of spots_total should remain the same). Once spots_open = 0, the slot should no longer show up.

    Example Services

    A yoga class or a beauty salon have the following floor plans and no active bookings

    Figure 1: Floor plan with no active bookings

    The availability feed for 2 slots at these merchants would look like:

    JSON

        {
      "availability": [
            {
              "spots_total": 6,
              "spots_open": 6,
              "duration_sec": 3600,
              "service_id": "1001",
              "start_sec": 1535817600, # Sept 1, 2018 4:00:00 PM GMT
              "merchant_id": "1001"
            },
            {
              "spots_total": 6,
              "spots_open": 6,
              "duration_sec": 3600,
              "service_id": "1001",
              "start_sec": 1535832000, # Sept 1, 2018 8:00:00 PM GMT
              "merchant_id": "1001",
            }
          ]
    }

    Example Services with a Booking

    Figure 2: Floor plan with one active booking

    Now a user books one of the spots. When a booking happens, a realtime update is issued to update the availability. In the next daily availability feed, this booking should be reflected. The availability feed for these merchants would have spots_open decremented by 1 for the Sept 1, 2018 4:00:00 PM GMT slot. The Sept 1, 2018 8:00:00 PM GMT slot remains unchanged.

    Feed Snippet with a Booking

    JSON

        {
      "availability": [
            {
              "spots_total": 6,
              "spots_open": 5,
              "duration_sec": 3600,
              "service_id": "1001",
              "start_sec": 1535817600, # Sept 1, 2018 4:00:00 PM GMT
              "merchant_id": "1001"
            },
            {
              "spots_total": 6,
              "spots_open": 6,
              "duration_sec": 3600,
              "service_id": "1001",
              "start_sec": 1535832000, # Sept 1, 2018 8:00:00 PM GMT
              "merchant_id": "1001",
            }
          ]
}

    Recurrence

    Parameter Definitions

    • recurrence: The representation of consistently repeating availability slots.
    • repeat_until_sec: The UTC timestamp of the end time of last slot that the availability repeats until.
    • repeat_every_sec: The number of seconds between successive availability slots. For example, if repeat_every_sec = 1800 (30 minutes), and the start_sec starts at 9:00 AM, the slots will repeat every 30 minutes at 9:00 AM, 9:30 AM, 10:00 AM, etc.
      • Note: There is no need to specify spots_open and spots_total, they are both assumed to be 1 unless there is a schedule_exception

    The recurrence method indicates availability on a daily basis for services that occur at regular intervals, for example, a service that happens every 30 minutes from 9:00 AM - 5:00 PM each day. With recurrence, you specify the duration of the slot, the first time in the day the slot occurs, how often that slot should repeat, and when on that same day it should stop repeating. Note: a new set of recurring slots needs to be specified for each day separately. If a slot is already booked within the time range you will specify a schedule exception. For example, repeat every half hour from 9 AM to 9 PM except from 11:00 AM to 11:30 AM. Each individual service will have its own recurrence and scheduling exceptions.

    Example Services

    A beauty salon has the following floor plan and no active bookings

    Figure 3: Floor plans with no active bookings. Assumes only 1 spot open per service (e.g. Sally provides haircut services every 30 minutes, but can only attend to 1 customer at a time.)

    The availability feed for 1 slot at these merchants would look like:

    Feed Snippet:

    JSON

        {
    "availability": [
          {
            "merchant_id": "1001",
            "service_id": "1001",  # haircut
            "start_sec": 1493888400, # May 4, 2017 9:00:00 AM GMT
            "duration_sec": 1800,
            "recurrence": {
              "repeat_every_sec": 1800,
              "repeat_until_sec": 1493915400 # May 4, 2017 4:30:00 PM GMT
            }
          }
        ]
    }

    Example Services with a Booking

    Figure 4: Floor plans with one active booking. Assumes only 1 spot open per service (e.g. Sally provides haircut services every 30 minutes, but can only attend to 1 customer at a time.)

    Now imagine that a user books a haircut with Sally at 12:30 PM. When a booking happens, a realtime update is issued to update the availability. In the next daily availability feed, this booking should be reflected. The availability feed for these merchants would have a scheduling exception during 12:30 PM - 1:00 PM for a service with a 30 min duration.

    Feed Snippet with a Booking:

    JSON

        {
      "availability": [
            {
              "merchant_id": "1001",
              "service_id": "1001",
              "start_sec": 1493888400, # May 4, 2017 9:00:00 AM GMT
              "duration_sec": 1800,
              "recurrence": {
                "repeat_every_sec": 1800,
                "repeat_until_sec": 1493915400 # May 4, 2017 4:30:00 PM GMT
              },
              "schedule_exception": [
                {
                  "time_range": {
                    "begin_sec": 1493901000, # May 4, 2017 12:30:00 PM GMT
                    "end_sec": 1493902800 # May 4, 2017 1:00:00 PM GMT
                  }
                }
              ],
            }
          ]
    }