Lease specification

  • Leases are an optional first step in booking an appointment, though CheckAvailability is recommended in v2 of the API.

  • The partner backend verifies appointment slot validity and availability, creating a temporary hold that expires automatically.

  • The lease_expiration_time can be modified by the backend, especially if the requested lease time is too long.

  • A Lease object contains details such as lease_id, merchant_id, service_id, start_time, duration, availability_tag, resources, client_reference, and lease_expiration_time.

Creating the lease is the first step when booking an appointment. The partner backend verifies that the requested appointment slot is valid and still available. Internally, the partner creates a temporary hold for the requested slot, which is set up to expire automatically at lease_expiration_time. The backend is allowed to modify lease_expiration_time, e.g. if the requested lease time is excessively long. The created lease is returned to the client.

// Temporary lease for an inventory slot
message Lease {
  // ID of the lease. Ignored when creating a lease.
  string lease_id = 1;

  // ID of the merchant for the slot
  string merchant_id = 2;

  // ID of the merchant service
  string service_id = 3;

  // Start time of the appointment slot
  google.protobuf.Timestamp start_time = 4;

  // Duration of the appointment slot
  google.protobuf.Duration duration = 5;

  // Opaque tag that identifies the availability slot and matches the value
  // provided in the availability feed.
  string availability_tag = 8;

  // The set of resources that disambiguates the appointment slot, e.g. by
  // indicating the staff member and room selected by the user.
  Resources resources = 9;

  // Unique identifier for this lease, chosen by the client. Serves as an
  // idempotency token for [ext.maps.booking.partner.v0.CreateLease] requests.
  string client_reference = 6;

  // Expiration time of the lease
  google.protobuf.Timestamp lease_expiration_time = 7;
}

// Reference to a [ext.maps.booking.partner.v0.Lease] that has been created via
// [ext.maps.booking.partner.v0.CreateLease]
message LeaseReference {
  // Lease ID
  string lease_id = 1;
}