API Example – Bookings

On this page

Booking session ID

The Server-generated booking_session_id identifies the sequence of your interactions with the API. You can grab it from BookingSet of the first response and then pass it in all subsequent requests related to that booking set.

Making new bookings

The input for new bookings must include the following:

• The account
  • Defines the available allowances through the active personal/team plan subscriptions.
  • Used to invoice the overage charges, if any.
• The owner of the booking
  • For member accounts, it must be that same user.
  • For team accounts, it can be any team member.
• A single resource to be booked

When updating the bookings, booking_session_id, account, and owner_user_id may be omitted.

Draft a booking

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      # account: { team_id: TEAM_ID, organization_id: ORGANIZATION_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Commit a booking

Committing a booking will draft and save that booking. Pass booking_id to update the existing booking. Note that it is possible to call bookingsCommit without calling bookingsDraft first.

mutation {
  bookingsCommit(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Payment preferences

By default, if the booking requires a payment, the system will choose the optimal available allowance for the given account and use as much of it as possible. You can also manually specify the allowance and the exact amount to be used.

Get the available allowances

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp

      # the optimal allowance and the resulting booking cost
      payment {
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }

      # all other allowances and the full payment option (no allowance usage)
      available_payments {
        account {
          account_id
        }
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }
    }
  }
}

Use a specific allowance

Set amount: 0 if you want to only apply the discount to overage charges, without consuming the allowance.

Use calculate: NO_ALLOWANCE to disable the selection of the optimal allowance and generate a full charge instead.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
        payment: {
          calculate: FIXED_ALLOWANCE
          allowance_usage: [{
              allowance_id: "ALLOWANCE_ID"
              amount: 2.5
          }]
        }
        # payment: { calculate: NO_ALLOWANCE }
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
      payment {
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }
    }
  }
}

Updating a booking

Change the booking times

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        booking_id: BOOKING_ID
        start_timestamp: 1577869200
        end_timestamp: 1577874600
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Cancel the booking

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        booking_id: BOOKING_ID
        is_cancelled: true
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      is_confirmed
      is_cancelled
    }
  }
}

Other features

Invoice the booking

Use payment: {charge: TODAY} to invoice the booking with a positive payment.total. This will create a new invoice with a single line item due today.

Alternatively, set payment: {charge: NOW} to charge this invoice immediately using the default payment method associated with the given account.

Add invitees to the booking

For existing users, please provide either user_id, or email. If you enter an email address for which an existing user is not found, one will be created using the given email.

When you edit a booking, existing invitees will be preserved, along with their invitation status. Set invitees: [] to remove them from a booking.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
        invitees: [
          { user_id: USER_ID }
          { email: "EMAIL" }
          { email: "EMAIL", name: "NAME SURNAME" }
        ]
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      invitees {
        user {
          user_id
          fullname
        }
        status
      }
    }
  }
}

Get the alternative bookings

The system suggests multiple alternatives for each booking based on the given preferences; e.g. resource type, hourly price, duration, etc.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      alternative_bookings {
        booking_id
        start_timestamp
        end_timestamp
        resources {
          resource_id
        }
        payment {
          total
        }
      }
    }
  }
}

Check the resource availability

query {
  resourceAvailability(
    input: {
      resource: { price_hour_to: 20 }
      start_timestamp: 1577869200
      end_timestamp: 1577874600
      duration_sec: 3600
    }
  ) {
    resource {
      resource_id
      title
    }
    available {
      start_timestamp
      end_timestamp
    }
  }
}