List bookings API returns different appt counts than "Team Performance" report

Questions
1

I’m working as a developer for a store owner who wants custom reporting for his Appointments. I’ve been using the GET/v2/bookings List bookings API to list all appointments in a given month. The strange thing is … the API responds with only ~50% of the bookings that happened in a given month.

I can’t figure out why only some bookings are being returned. (I did write to Support two days ago, but haven’t heard back). Can anyone explain what is going on here? Is it a bug or did I misunderstand something here?

Expected behavior

  1. I use the Square Developer Tools API Explorer to make a new List bookings API request
  2. In the parameters, I enter …
    • limit: 500
    • start_at_min: 2025-02-01T00:00:00.000Z
    • start_at_max: 2025-03-01T00:00:00.000Z
  3. I use a production token so that I’m querying real data
  4. I run the query by hitting Run request
  5. I count the number of bookings returned. Let’s say I get back 128 bookings from the API.
  6. I open Team Performance Report from the Square Dashboard
  7. I adjust the time filters to match my API query: 2025-02-01 through 2025-03-01
  8. I should see a total number of appointments (128) that matches the API response (128).

Actual behavior

  1. (same as above)
  2. (same as above)
  3. (same as above)
  4. I run the request in the API Explorer as above and I get back this unpaginated JSON response: Square List Bookings API Response - Pastebin.com
  5. I count the number of bookings and I get exactly 128 bookings.
  6. I open Team Performance Report from the Square Dashboard
  7. I adjust the time filters to match my API query: 2025-02-01 through 2025-03-01
  8. I see a total of 210 bookings reported by the UI
    screenshot of team performance report
    screenshot of team performance report2984×1720 271 KB

Steps to reproduce

  1. Add some bookings to the month of Feb 2025 in your Square Appointments calendar
  2. Use the Square Developer Tools API Explorer to make a new List bookings API request and use the parameters …
    • limit: 500
    • start_at_min: 2025-02-01T00:00:00.000Z
    • start_at_max: 2025-03-01T00:00:00.000Z
  3. Count the number of bookings you get back as a JSON response. You can use an online JSON analyzer to make it easy.
  4. Sign into Square with the same account you used for the API Explorer, and go to Team Performance Report
  5. Set the date filters to 2025-02-01 through 2025-03-01
  6. Sum the total number of bookings
  7. Compare the count from (3) with the count from (6)
2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Create and Manage Bookings
Onboard to Square Appointments
Handle Bookings Webhook Events

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

The ListBookings API endpoint returns bookings based on the permissions of the application making the request. If your application has buyer-level permissions, it can only access and view bookings that it created. If your application has seller-level permissions, it can access and view every booking of a seller.

If you’re seeing only about 50% of the bookings, it’s possible that your application has buyer-level permissions and is therefore only able to access the bookings it created. To access all bookings, your application would need seller-level permissions.

Also, keep in mind that the ListBookings API endpoint returns bookings in pages. If there are more bookings than can fit in a single page, you’ll need to use the cursor provided in the response to retrieve the next page of results.

If you’ve checked these factors and are still experiencing issues, it might be a good idea to double-check the specific parameters you’re using in your API request.

This answer was reviewed by @Bryan-Square.

4

Also was there a pagination cursor in the API response? :slight_smile:

5

Nope, no pagination cursor in the response. See the raw response in my original post — I can’t paste it here because Pastebin links result in 422 errors :roll_eyes:

6

Also, re permissions, I have the Bearer token of the store owner, so this is not the fix.

Support replied today and acknowledged the bug, saying it appears to be related to one-time vs recurring appointments:

I’m Lance, a Developer Success Engineer on our Developer Experience team. I can help with API-related inquiries.

On a side note: Do not share your access token, even to Square. Keep it secure! Gives full API access to the Square account, to read and write. All my team would need in the future is your application id: sq0idp-2QfHIs08XvVtZLJ2M4HI8g.

I’ve taken a look at the Seller Dashboard report you linked, and made a fresh ListBookings API call, and it would seem there’s a notable different in the number of appointments appearing in the API.

My best guess, is that most of these 1st party appointments are recurring appointments, which cannot be found via the Booking API. If this is the case, than only 69 appointments were one time appointments, visible in the booking API.

But I’ve raised the question with the Square team, so they could give us a sure answer on what you’re seeing in the Booking API. I’d expect the team to be slow to respond. Feel free to ask me for an update on Monday, so I can try and ping the team again.

7

Ah, yes recurring appointments aren’t returned with the API at this time. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slight_smile: