Questions about a custom availability calendar, overlapping bookings, and external reservation integration in Japan

Questions
1

Hello Square Developer Support,

I run Centre hairsalon in Japan. Square Japan Support referred me here.

We would like to keep Square as our main appointment system and clarify whether these three workflows are officially supported.

  1. External availability calendar → Square-hosted booking

Customers would select a service, staff member, and appointment time on our website using an availability grid (○ = available, × = unavailable), then move to Square’s hosted booking page.

  • Can we pass these selections through officially supported URL parameters or deep links?
  • Can customers proceed directly to entering their personal information and confirming the booking without selecting everything again?
  • Can we retrieve availability through the Bookings API without accessing customer personal information?

Our goal is to keep all customer information entry and booking confirmation on Square’s hosted page.

  1. Overlapping appointments for the same stylist

In our salon, a stylist may serve another customer during the processing time of a color or perm service, with an assistant helping.

  • Can Square model processing periods during which the same stylist is available for another appointment?
  • Can customers book those periods online?
  • Can the Bookings API create partially overlapping appointments for the same staff member? Does this depend on seller-level permissions or plan settings?
  • What is the officially supported way to allow controlled overlaps while preventing conflicts during hands-on service time?
  1. Automatically blocking Square availability from external booking emails

We receive reservations from Hot Pepper Beauty and Rakuten Beauty.

We would like to use their confirmation, modification, and cancellation emails to automatically block, update, or reopen the corresponding time in Square.

  • Does Square offer an official integration for these platforms?
  • If not, can our integration use Square APIs to create and update busy periods without creating customer profiles or storing customer names, email addresses, or phone numbers in Square?
  • Is there an API for personal events or other calendar blocks? If not, what supported alternative would you recommend?
  • How should we check for conflicts before blocking a time, and what limitations apply to preventing double bookings?

We understand that parsing external emails would be handled by our integration and that those emails may contain personal information. We would prefer a design that uses only the reservation identifier, service, staff member, and date/time, with minimal data retention.

For each workflow, please clarify what is supported in Japan, any required subscription plans and API permissions, and the relevant documentation. If a workflow is unsupported, please suggest an official alternative.

Thank you.

3

Hi @imasuke,

Hi, thanks for the detailed write-up.

1. External availability calendar → Square-hosted booking
You can read availability with the Bookings API’s SearchAvailability endpoint, and the response doesn’t include customer personal information. The Bookings API rate limit is fairly low, so cache availability on your side and refresh it periodically. Don’t query it live for every page view.

  • SearchAvailability returns available times, service identifiers, and staff identifiers and not customer names, emails, or phone numbers. No customer record is needed to search.

Required permissions:APPOINTMENTS_READ for buyer-level searches; APPOINTMENTS_READ + APPOINTMENTS_ALL_READ for seller-level searches.
Availability API documentation

  • Can customers enter their information and confirm on Square?
    Yes, using Square’s normal hosted booking flow. What is unconfirmed is whether selections from their external calendar can carry into that flow.
  • Official alternative that keeps customer entry on Square: Japan online-booking documentation
  • The only officially supported URL/deep-link mechanism is being able to see booking_id and location_id but this is not recommended: Book Online with Square. Our recommendation for this use case is to integrate your website with Bookings API to create appointments/bookings using the API.

2. Overlapping appointments for the same stylist

  • Yes! you can do overlapping appointments with the same stylist, you are able to do this on the Square Booking API, (just make sure you utilize idempotency_key correctly for each API request),
  • It does not work online on Squares appointment bookings flow
  • The officially supported way to allow overlaps is using by allowing customers to book using Square’s Booking API, this would mean hosting your own booking flow using Square API.

3. Blocking time from Hot Pepper Beauty / Rakuten Beauty

  • we do not have integration with these platforms but you can consider looking at some integrations we have for booking and reservations 予約・スケジュールの管理 | Square アプリマーケット
  • you can block off sections of time for your team members without creating customer_ids. But, you will need a customer_id to create an appointment.
  • I recommend using the Manage calendar sync option in the appointments tab to connect Google calendar to your bookings Japan Google Calendar sync documentation
  • You can check for conflicts, use SearchAvailability to check whether Square offers a slot for the relevant staff member, service, and duration. This searches bookable service slots; it is not a general-purpose conflict check for arbitrary calendar blocks.
5

Hi helner-square,

Thank you very much for your detailed response. This is extremely helpful.

Before starting development, I would like to clarify three important points.

  1. Custom calendar with Square-hosted booking

Can customers select a service, stylist, date, and time on our custom calendar, then complete their booking on Square’s hosted booking page with those selections preserved?

If this is not supported, is there another officially supported solution that keeps customer information entry entirely within Square?

  1. Overlapping bookings and customer privacy

We would like to allow overlapping appointments for the same stylist using the Bookings API.

Is there a supported way to achieve this while ensuring that customer names, email addresses, and phone numbers are entered and managed only by Square, without passing through or being stored on our own server?

  1. External reservation synchronization

We receive reservation notification emails from Hot Pepper Beauty and Rakuten Beauty.

Can we automatically create, update, or remove blocked time slots in Square through an API, using only the appointment time, duration, and staff identifier, without creating a customer record?

If possible, which API endpoints would you recommend?

Our priority is to maintain strong customer privacy while improving the booking experience for our small hair salon in Japan.

Thank you again for your support.

Best regards,
Shunsuke Imai
Centre hairsalon

6

Hi @imasuke,

1. Custom calendar → Square-hosted booking

There is no documented, supported handoff that preserves all four selections service, stylist, date, and time from your custom calendar and takes the customer directly to entering their information.

The supported alternative is Square’s hosted booking flow, linked from your website or added using Square’s booking widget. An advanced widget can be configured for specific services and staff, but that is not a handoff of a date and time selected in your custom calendar.

This keeps customer information entry within Square. See the Japan online-booking guide.

2. Overlapping appointments while keeping customer information in Square

For your color/perm use case, Square’s native processing-time feature is the supported option. It separates a service into initial, processing, and final durations, allowing another appointment during the processing period. My earlier statement that this cannot work through Square’s online booking flow was too broad.

This feature is available in Japan with Square Appointments Plus or Premium. Customers can use Square’s booking flow rather than entering their details into your application. See the Japan processing-time guide.

Separately, the Bookings API supports double bookings with seller-level permissions and an eligible paid plan. API bookings reference a Square customer_id; you do not have to send the customer’s name, email, and phone with every booking if their profile already exists in Square. However, there is no documented Square-hosted customer-information-only step to attach to your custom API booking flow.

For your privacy requirement, I recommend native processing time with Square-hosted booking rather than custom API-created overlaps.

3. Blocking time from external reservations without customer records

The public Bookings API does not expose endpoints to create, update, or delete personal events or arbitrary calendar blocks. There is a difference between blocks created in Square’s interface from those available through the API.

The supported alternative is Google Calendar synchronization, available in Japan with Appointments Plus or Premium:

  • Connect a Google Calendar to the relevant Square staff calendar using Import Only.
  • Have your integration create, change, or delete Google Calendar events marked Busy.
  • Use a generic event title and omit customer details and attendees. These import as personal/blocking events, not customer appointments.

For automation, the relevant Google Calendar API methods are events.insert, events.patch, and events.delete and not Square Bookings endpoints.

See the Japan Google Calendar sync guide. Synchronization can take time, so this is not an immediate reservation lock or a guarantee against simultaneous bookings.