Lease specification

  • Leases are optional in v2 and primarily used for creating temporary holds on appointment slots before booking.

  • The Lease message contains information like merchant and service IDs, appointment details, resources, and an expiration time managed by the partner backend.

  • LeaseReference allows referencing a previously created Lease using its unique ID.

  • Partners verify slot availability and create a temporary hold using CreateLease, returning the Lease to the client.

  • client_reference serves as an idempotency token for CreateLease requests ensuring unique lease creation.

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;
}