**Applies to:** [Bookings API](https://developer.squareup.com/reference/square/bookings-api) | [Booking Custom Attributes API](/docs/booking-custom-attributes-api/overview) | [Locations API](/docs/locations-api) | [Team API](/docs/team/overview) | [Customers API](/docs/customers-api/what-it-does) | [Catalog API](/docs/catalog-api/what-it-does)

<Subheading>Learn about using the Bookings API to create applications for Square sellers and their customers to create and manage bookings.</Subheading>

## Overview

A booking refers to a reservation of a service provided by a member of the seller's staff for a customer over a specified time duration at a particular time and location.

Both the seller (or a team member, called staff) and the customer (also known as the buyer) can create and manage a booking. However, the seller has more control and access to bookings than the buyer. Therefore, seller and buyer operations need different access permissions, called seller-level and buyer-level permissions in this topic.

You can add custom attributes to the [Booking](https://developer.squareup.com/reference/square/objects/Booking) object. To do so, use the [Booking Custom Attributes API](/docs/booking-custom-attributes-api/overview).

## Seller-level and buyer-level permissions

Seller-level permissions grant an application full visibility into a seller's calendar and they enable full control of the seller's bookings. A seller must have a subscription to Appointments Plus or Premium to use this feature.

Buyer-level permissions grant partial visibility into a seller's calendar, limited to bookings created by the calling application. Buyer-level permissions enable limited control of bookings for buyers only. All sellers have access to this feature.

With seller-level permissions, your application can do the following:

* **Access and view every booking of a seller** - For example, calling [ListBookings](https://developer.squareup.com/reference/square/bookings-api/list-bookings) can return every booking in the seller's calendar.
* **Generate bookings webhooks**  - Every change to a booking is sent to webhooks, as a [booking.created](https://developer.squareup.com/reference/square/bookings-api/webhooks/booking.created) or [booking.updated](https://developer.squareup.com/reference/square/bookings-api/webhooks/booking.updated) event.
* **Create double bookings**  - Allows service of different customers at the same time or location. It can also create off-hour bookings outside the seller's regular business hours.

With buyer-level permissions, your application can do the following:

* **Access and view bookings that it created** - Calling `ListBookings` returns bookings created by the application only.
  * An application must create a booking to get event notifications about changes to a booking. This applies if the booking was created using the API or if an API-created booking is updated using the API, the Square Dashboard, or the seller's booking site.
  * An application cannot create double bookings for the user or create a booking outside the seller's regular business hours.

## Bookings API operations

Using the Bookings API, your application can perform the following tasks:

* **Retrieve bookings**  - Inspect the details of each booking, including services to be provided, bookable team members providing the services, and the location where the customer receives the services.
* **Search for the availability of a service, team member, and location** - The returned availability can be turned into a booking by adding a customer.
* **Maintain bookings**  - Including the creation, update, and cancellation of a booking. To create, update, or cancel a seller-level booking, the targeted seller must have subscribed to a paid Appointments subscription plan and your application must have seller-level permissions.

## Integration with paid subscription plans

[Square Appointments Plus or Appointments Premium](https://squareup.com/appointments/subscription/choose_plan) is a monthly paid subscription plan to Square Appointments. When a seller subscribes to a paid subscription plan, you can call the Bookings API to create, update and cancel seller-level bookings with the seller. By default, a seller subscribes to the free subscription plan that offers basic Appointments features. With the free subscription plan, you can call the Bookings API to create, update or cancel buyer-level bookings with the seller and to access any readable property of a booking.

To integrate the Bookings API with a paid Appointments subscription plan of a seller for creating, updating or canceling a seller-level booking, your application must have the writeable seller-level permissions. The OAuth scopes must include the following permissions:

* `APPOINTMENTS_WRITE`
* `APPOINTMENTS_ALL_WRITE`

When using the Bookings API with the free Appointments subscription plan, the application must have all of the buyer-level permissions plus the readable seller-level permission. The OAuth scopes can include the following permissions:

* `APPOINTMENTS_READ`
* `APPOINTMENTS_WRITE`
* `APPOINTMENTS_ALL_READ`
* `APPOINTMENTS_BUSINESS_SETTINGS_READ`

You can call the Bookings API to verify whether a seller supports creating, updating or canceling a seller-level booking, before attempting to carry out such operations. To do so, call [RetrieveBusinessBookingProfile](https://developer.squareup.com/reference/square/bookings-api/retrieve-business-booking-profile) and inspect the response for the [support_seller_level_writes](https://developer.squareup.com/reference/square/objects/BusinessBookingProfile#definition__property-support_seller_level_writes) attribute. Only when the returned value is `true` can you proceed successfully to create, update, or cancel seller-level bookings.  

When a seller doesn't have the Appointments Plus or Premium subscription plan, all the API calls targeted at the seller with buyer-level permissions and those with seller-level readable permissions succeed. However, API calls targeted at the seller with seller-level writeable permissions fail with a `403` response containing the following error message:

```json
{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "FORBIDDEN",
      "detail": "Merchant subscription does not support write operations."
    }
  ]
}
```

When a seller subscribes to an Appointments plan, the same plan applies to all active locations of the seller and each location is billed the same price of the chosen plan. A seller cannot subscribe to one plan at a location and another plan at another location.

## Integration with other Square APIs

A booking application using the Bookings API uses several other Square APIs. They include:

* The [Locations API](/docs/locations-api), which is used to choose a seller's business location where a customer receives a booked service provided by a team member of the seller.
* The [Team API](/docs/team/overview), which is used to choose a team member of the seller to provide a booked service.
* The [Customers API](/docs/customers-api/what-it-does), which is used to create a new customer or search for an existing customer for a booking.
* The [Catalog API](/docs/catalog-api/what-it-does), which is used to create a bookable service that is represented by a [CatalogItemVariation](https://developer.squareup.com/reference/square/objects/CatalogItemVariation) object.

A [team member](https://developer.squareup.com/reference/square/objects/TeamMember) who can be booked to provide a service must be a bookable team member. The seller or a designated representative of the seller can make a team member a bookable team member by adding the team member (an employee) to a service in the Square Dashboard. This task cannot be delegated to any third-party developer calling the Square API.

## See also

* [Bookings API Concepts](/docs/bookings-api/get-ready-to-use-the-api)
* [Onboard to Square Appointments](/docs/bookings-api/onboard-to-the-api)
* [Create and Manage Bookings](/docs/bookings-api/use-the-api)
* [Handle Bookings Webhook Events](/docs/bookings-api/use-webhooks)