Microsoft Graph Bookings API: what it can and can't do

Microsoft Graph has a full REST API for shared booking pages: you can create, read, update and delete businesses, services, staff, customers, custom questions and appointments, publish or unpublish a page, list appointments in a date range and read staff availability. As of October 2026 it has three gaps that decide most projects: it doesn't cover "Bookings with me" pages at all, it has no webhooks or change notifications, and its availability call returns free and busy blocks rather than bookable slots. Everything runs under https://graph.microsoft.com/v1.0/solutions/bookingBusinesses, and the booking business ID is the page's mailbox address.

Resources and what each is for#

Two details trip people up. On a staff member, availabilityIsAffectedByPersonalCalendar corresponds to the "Events on Microsoft 365 calendar affect availability" switch in the web app: Microsoft says that only when it's true does Bookings check the person's Microsoft 365 calendar before booking. And scheduler and teamMember were added to an existing enum, which is why they're hidden unless you ask for them.

v1.0 or beta#

Use v1.0. Every resource in the table above, plus bookingPageSettings, is in v1.0, and Microsoft says beta APIs "are subject to change" and that production use "is not supported".

Things worth knowing if you read both sets of pages:

• The path differs. v1.0 uses /v1.0/solutions/bookingBusinesses. The beta overview examples use /beta/bookingBusinesses without solutions.
• The pages disagree with each other. The beta overview's use-case table leaves out customers and custom questions, and the beta bookingBusiness page lists no customQuestions relationship, while the method table on the same page includes "List customQuestions". Trust the method pages over the overview.
• The licence line is out of date. Both overviews say to "make sure the business has a Microsoft 365 Business Premium subscription". The Bookings FAQ lists more than a dozen plans that include Bookings. Business Premium isn't required.

Permissions#

There are four Bookings permissions (Bookings.Read.All, BookingsAppointment.ReadWrite.All, Bookings.ReadWrite.All, Bookings.Manage.All), each delegated or application. Application versions need admin consent and reach every booking mailbox in the tenant; none can be scoped to one page as of October 2026. Two calls only work one way: getStaffAvailability is application-only, and creating a booking business is delegated-only. The Graph permissions reference itself describes the application versions of Bookings.ReadWrite.All and Bookings.Manage.All as acting "on behalf of the signed-in user", which application permissions never do; treat that wording as a documentation error. The full least-privilege table and the 403 problem are in Graph permissions for Bookings.

Apps that create or update appointments with application permissions "must adhere to business rules": business hours, the service duration, minimum and maximum lead time, and allowStaffSelection (shown as Staff control in the web app) if you pass staff IDs. Only administrators can override the rules in the UI.

Clouds#

The Bookings method pages list the global service, US Government L4 and US Government L5 (DoD) as supported, and the China cloud operated by 21Vianet as not supported. That is wider than the Power Automate connector, which isn't available in GCC, GCC High or DoD. So for a tenant in GCC High or DoD, Graph is the documented way to automate Bookings.

Throttling#

Bookings limits each app ID and booking mailbox pair to four concurrent requests, on both v1.0 and beta. Hitting the limit on one mailbox doesn't affect the same app on another mailbox, so a tenant-wide sync can run one worker per mailbox. Keep requests sequential within a mailbox and back off on HTTP 429. The Bookings section of the throttling page lists no other limit; the general Graph limits still apply.

What you can't do (as of October 2026)#

• Bookings with me. Microsoft says the API "is not applicable for personal bookings" (Microsoft now calls them Personal Bookings). There is no Graph resource for meeting types or personal booking links.
• Get notified of changes. Bookings isn't in the list of resources that support Graph change notifications. You poll calendarView and diff the results; the pattern is in Bookings webhooks and alternatives.
• Filter by creation date. There's no "created since" query, which is why polling compares IDs.
• Read RefID tracking data. bookingAppointment has no tracking field. The value only appears in the TSV export and the Power Automate trigger. See RefID tracking not working.
• List more than 500 businesses in one call, or page through them.
• Restrict an app to one page with a permission setting.
• Ask for bookable slots. You compute them from getStaffAvailability and the service rules.

A first request#

App-only access uses the client credentials flow against your tenant. Register an app in Microsoft Entra ID, grant Bookings.Read.All as an application permission, have an admin consent, then:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={app-id}&client_secret={secret}&scope=https://graph.microsoft.com/.default&grant_type=client_credentials

GET https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/sales@contoso.com/calendarView?start=2026-10-20T00:00:00Z&end=2026-10-27T00:00:00Z
Authorization: Bearer {access_token}

The same read in Microsoft Graph PowerShell is Get-MgBookingBusinessCalendarView -BookingBusinessId sales@contoso.com -Start "2026-10-20T00:00:00Z" -End "2026-10-27T00:00:00Z" from the Microsoft.Graph.Bookings module. Remember that the times in start and end are read using the offset you give them, not the Prefer: outlook.timezone header.

If you're building a booking front end rather than a report, read building a custom Bookings booking page before you start; the slot logic is most of the work.

What we saw when testing (September 2026)#

We haven't run Graph against a live tenant, because that needs admin consent we don't have. What we did test is the separate, undocumented API that the public booking page calls without sign-in, which people often find when Graph's permissions look too heavy:

• It sends no CORS headers. An OPTIONS request returned 401 with no Access-Control-* headers, so browser code on your site can't call it; it needs a server in between.
• Latency depends on one header. Without x-anchormailbox set to the business mailbox, requests still succeeded but took 15 to 48 seconds. With it, reads took roughly 0.3 to 1.3 seconds from our server, and a successful booking about 5.5 seconds.
• It validated less than Graph says it does. It accepted a booking in the past and one over a busy Outlook block, and only rejected clashes with other Bookings appointments. Graph with application permissions is documented to enforce the business rules above.

It's unsupported and can change with any Microsoft release, so treat it as something to pin with tests, not a contract.

Doing this with BookingsXP#

If what you need from the API is "show our Bookings times on our website and know when someone books", the BookingsXP booking widget does that from your public booking page link, with no app registration, Graph permission or admin consent, and sends a signed webhook for each widget booking. It only sees bookings made through the widget, and it can't read your customer list or other pages the way Graph can. BookingsXP is independent and not affiliated with or endorsed by Microsoft.