Square Appointments
Square Appointments API: what WhatsDo reads and writes
The technical half of the Square connector, for the engineer deciding whether to route through WhatsDo or build onto Square directly.
What WhatsDo reads from a Square account
The import is a read. It runs at connection time, refreshes as the merchant changes things, and the merchant reviews it before an agent sees anything.
- 01Locations, with the timezone and currency each one operates in.
- 02Bookable services with their names, durations and prices.
- 03Business hours and staff availability as Square holds them.
- 04Open slots, read live at request time, with no hold placed on the calendar.
- 05Nothing beyond that. Client records and booking history are not part of the agent view.
What WhatsDo writes back
One kind of object, after one explicit confirmation of an immutable summary: service, time, timezone, price and currency. The write itself runs in closed beta against a controlled merchant.
- 01An appointment in the merchant's own Square account, created after that confirmation, on the closed-beta write path.
- 02A booking identifier intended to match the Square record, returned to the calling agent.
- 03Nothing else. Services, staff, prices and business hours are never modified.
- 04No cancellation and no reschedule. That path is not exposed to agents.
- 05No payment. Agent-initiated payment is not live on this path.
Where the boundary sits
The merchant owns the authorization and can end it at any moment. Your agent never holds a Square credential and never sees one.
- 01Authorization is server-side. No provider key reaches a browser and none reaches your agent.
- 02The merchant grants only what the connector needs: reading services and availability, and creating appointments.
- 03Revoking the authorization inside Square removes agent access immediately.
- 04Repeating the same booking request returns the existing booking rather than creating a second one.
- 05A failure returns a stable machine-readable code and a recovery path. An unknown result is never reported as success.
- 06Any step a human completed is flagged as manual fallback and excluded from automated success.
How this differs from integrating with Square yourself
Building straight onto Square is a reasonable choice with a different scope. The trade is breadth of API against breadth of merchants.
Straight onto Square
- You implement the authorization flow, token refresh and merchant onboarding for every merchant you want to reach.
- You map Square's own catalog and availability model into whatever shape your agent expects, and again for the next platform.
- You reach the whole Square surface, including operations WhatsDo does not expose to agents today.
Through WhatsDo
- One contract, one confirmation gate, one error taxonomy, and the backend that answered named in every response.
- The same contract when a second backend goes live, so an agent written once is not rewritten per platform.
- Coverage is narrow and stated. Square Appointments availability today, the booking write in closed beta.
Where to start
Merchant setup and the developer contract are deliberately two different pages, because they are read by two different people.
- Exact field mapping, endpoints and auth arrive with credentials during the closed beta rather than on a public page.
- Testing runs against a WhatsDo-controlled merchant, so a first booking is never written into a real business.
- A second backend does not change the contract, so the work you do here is not Square-specific.
Questions from engineers
Is this the Square Appointments API?+
No. WhatsDo talks to Square on the merchant's behalf and your agent talks to the WhatsDo contract. Every response names the backend that answered, so you always know Square handled it.
Do I need my own Square developer account?+
Not to book through WhatsDo. The merchant authorizes WhatsDo inside their own Square account, and your agent holds WhatsDo credentials only.
Can an agent cancel or reschedule through this path?+
No. The agent path creates a booking on the closed-beta write and stops there. Cancellation and reschedule are handled in Square by the business or the client.
What happens if the slot is taken while the agent confirms?+
The write fails with a stable error code and the agent is sent back to fresh availability. No partial booking and no duplicate is left behind.
Which Square objects map to the contract?+
Locations, bookable services with duration and price, availability in an explicit timezone, and the appointment record itself. The exact field mapping ships with credentials, not on this page.
Build against one contract and let the merchant keep Square.
Your first calls run against a controlled merchant, never a live business.
Run a business? Start here