REST Resource: inventory.partners.merchants.services.availability

Resource: Availability

An availability slot of the merchant's service, indicating time and number of spots.

JSON representation
{
  "startTime": string,
  "duration": string,
  "spotsTotal": string,
  "spotsOpen": string,
  "availabilityTag": string,
  "resources": {
    object(Resources)
  },
  "paymentOptionId": [
    string
  ],
  "recurrence": {
    object(Recurrence)
  },
  "scheduleException": [
    {
      object(ScheduleException)
    }
  ],
  "deposit": {
    object(Deposit)
  },
  "noShowFee": {
    object(NoShowFee)
  },
  "requireCreditCard": enum(RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "schedulingRuleOverrides": {
    object(SchedulingRuleOverrides)
  },
  "confirmationMode": enum(ConfirmationMode)
}
Fields
startTime

string (Timestamp format)

Start time of the appointment slot.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

duration

string (Duration format)

Duration of the appointment slot

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

spotsTotal

string (int64 format)

Number of total spots and open spots of this availability. Examples:

  • Yoga class of 10 spots with 3 booked: availability {spotsTotal: 10, spotsOpen: 7 ...}
  • Chair massage session which is already fully booked: availability {spotsTotal: 1, spotsOpen: 0 ...}

Note: If sending requests using the availability compression format defined below, these two fields will be inferred.

  • A Recurrence implies spotsTotal=1 and spotsOpen=1.
  • A ScheduleException implies spotsTotal=1 and spotsOpen=0.

spotsOpen

string (int64 format)

Number of open spots.

availabilityTag

string

An optional opaque string to identify this availability slot. If set, it will be included in the requests that book/update/cancel appointments.

resources

object(Resources)

Optional resources used to disambiguate this availability slot from others when different staff members, or rooms are part of the service.

E.g. the same Yoga class with two 2 instructors:

availability { resources { staffId: "1" staffName: "Amy" }
               spotsTotal: 10 spotsOpen: 7 }
availability { resources { staffId: "2" staffName: "John" }
               spotsTotal: 5 spotsOpen: 2 }

paymentOptionId[]

string

A list of ids referencing the payment options which can be used to pay for this slot. The actual payment options are defined at the Merchant level, and can also be shared among multiple Merchants.

This field overrides any payment_option_ids specified in the service message. Similarly payment_option_ids specified here do NOT have to be present in the service message, though must be defined at the Merchant level.

recurrence

object(Recurrence)

The recurrence information for the availability, representing more than one start time. A recurrence should contain appointments for one working day.

scheduleException[]

object(ScheduleException)

Times when this service cannot be scheduled. To limit the number of scheduleException messages, consider joining adjacent exceptions.

deposit

object(Deposit)

Optional deposit for this availability. Overrides the service deposit if one was specified.

noShowFee

object(NoShowFee)

Optional no show fee for this availability. Overrides the service no show fee if one was specified.

requireCreditCard

enum(RequireCreditCard)

Indicates whether the user must provide a credit card in order to book this availability slot. If the value is not set, it is inherited from the service level if it's set there. (optional)

ticketTypeId[]

string

Indicates a list of supported ticket types for this availability slot. If unset, all ticket types in the parent service are available for this slot. Note that the values of this field must be defined in the parent service. Examples:

  • Service with four ticket types: TicketType {ticketTypeId: "adult_1" shortDescription: "Adult weekdays"} TicketType {ticketTypeId: "adult_2" shortDescription: "Adult weekends"} TicketType {ticketTypeId: "youth_1" shortDescription: "Youth weekdays"} TicketType {ticketTypeId: "youth_2" shortDescription: "Youth weekends"}

To represent the inventory during the weekdays: availability {ticketTypeId: "adult_1" ticketTypeId: "youth_1"...}. To represent the inventory during the holidays: availability {ticketTypeId: "adult_2" ticketTypeId: "youth_2"...}.

  • Service with three ticket types: TicketType {ticketTypeId: "adult" shortDescription: "Adult"} TicketType {ticketTypeId: "youth" shortDescription: "Youth"} TicketType {ticketTypeId: "senior" shortDescription: "Senior"}

To indicate that all three ticket types are available for this time slot, use either availability {ticketTypeId: "adult" ticketTypeId: "youth" ticketTypeId: "senior" ...} or `availability {...}' (do not set ticketTypeId in this slot).

(optional)

schedulingRuleOverrides

object(SchedulingRuleOverrides)

Availability scheduling rules. If fields are populated, they will override any corresponding scheduling rules on the service-level SchedulingRules.

confirmationMode

enum(ConfirmationMode)

The confirmation mode that will be used when booking this availability. Attempts to create bookings for availabilities with a confirmation mode of CONFIRMATION_MODE_SYNCHRONOUS must be immediatlely confirmed or denied. Attempts to create bookings for availabilities with confirmation mode of CONFIRMATION_MODE_ASYNCHRONOUS must be either immediately denied or created with status PENDING.

Resources

A resource is used to disambiguate availability slots from one another when different staff members, or rooms are part of the service. Multiple slots for the same service and time interval can co-exist when they have different resources.

JSON representation
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": number
}
Fields
staffId

string

Optional ID for a staff member providing the service. This field identifies the staff member across all merchants, services, and availability records. It also needs to be stable over time to allow correlation with past bookings. This field must be present if staffName is present.

staffName

string

Optional name of a staff member providing the service. This field will be displayed to users making a booking, and should be human readable, as opposed to an opaque identifier. This field must be present if staffId is present.

roomId

string

An optional ID for the room the service is located in. This field identifies the room across all merchants, services, and availability records. It also needs to be stable over time to allow correlation with past bookings. This field must be present if roomName is present.

roomName

string

An optional name for the room the service is located in. This field will be displayed to users making a booking, and should be human readable, as opposed to an opaque identifier. This field must be present if roomId is present.

partySize

number

Applicable only for Dining: The party size which can be accommodated during this time slot. A restaurant can be associated with multiple Slots for the same time, each specifying a different partySize, if for instance 2, 3, or 4 people can be seated with a reservation.

Recurrence

Recurrence messages are optional, but allow for a more compact representation of consistently repeating availability slots. They typically represent a day's working schedule. ScheduleException messages are then used to represent booked/unavailable time ranges within the work day.

Requirements:

  1. The expansion of availability slots or recurrences must NOT create identical slots. If the ids, startTime, duration, and resources match, slots are considered identical.
  2. Do NOT mix the standard availability format and recurrence within the slots of a single service. Recurrence benefits merchants/services that offer appointments. The standard format is geared towards merchants/services with regularly scheduled classes.
  3. Recurrences should not last for more than 24 hours.
JSON representation
{
  "repeatUntil": string,
  "repeatEvery": string
}
Fields
repeatUntil

string (Timestamp format)

The inclusive maximum UTC timestamp the availability repeats until.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

repeatEvery

string (Duration format)

Defines the time between successive availability slots.

Example: An availability with a duration of 20 min, a repeatEvery of 30 min, a startTime of 9:00am, and a repeatUntil of 11:00am will yield slots at 9-9:20am, 9:30-9:50am, 10-10:20am, 10:30-10:50am, 11-11:20am. (required)

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

ScheduleException

ScheduleException messages represent booked/unavailable time ranges within the workday, which are exceptions to the recurrence described above. As time slots are booked, the list of exceptions should be updated to reflect the newly unavailable time ranges. The recurrence itself shouldn't be modified.

JSON representation
{
  "timeRange": {
    object(TimeRange)
  }
}
Fields
timeRange

object(TimeRange)

The time range of the exception. Any slots described by the recurrence which overlap this closed-open time range will be considered unavailable.

Example: If the recurrence specifies a duration of 20 min, a repeatEvery of 30 min, a startTime of 9:00am, and a repeatUntil of 11:00am, then a ScheduleException with a timeRange of 9:45am-11:00am would make unavailable the slots at 9:30-9:50am, 10-10:20am, and 10:30-10:50am.

Note that because the time range is closed-open, the slot beginning at 11am slot would not be impacted.

SchedulingRuleOverrides

Availability level scheduling rules.

JSON representation
{
  "lastBookableSec": string,
  "firstBookableSec": string
}
Fields
lastBookableSec

string (int64 format)

The last time (in seconds) that this slot is able to be booked. This timestamp must be before the startSec of the slot to be respected (if users should be able to book after the start time, use service level SchedulingRules.min_booking_before_end_time). If present, will override anything specified in the min_booking_buffer of the corresponding Service's SchedulingRules.

firstBookableSec

string (int64 format)

The first time (in seconds) that this slot is able to be booked. This timestamp must be before the startSec of the slot, or lastBookableSec if specified.

ConfirmationMode

The confirmation modes used when booking availabilities.

Enums
CONFIRMATION_MODE_UNSPECIFIED The confirmation mode was not specified. Synchronous confirmation will be assumed.
CONFIRMATION_MODE_SYNCHRONOUS Bookings for this availability will be confirmed synchronously.
CONFIRMATION_MODE_ASYNCHRONOUS Bookings for this availability will be confirmed asynchronously.

Methods

replace

Replaces the Availability of an existing Service of a merchant managed by the specified aggregator, and returns it.