Square Appointments, Catalog & Orders
Book, reschedule and cancel Square Appointments, check open slots and staff, look up services, prices and stock in the catalog, and find customers and orders. Built for salons, spas, clinics and retail stores that run on Square. Curated from Square's official OpenAPI specification (Connect API v2).
Connect this API to an AI agent Browse all specs
What you can do with Square Appointments, Catalog & Orders via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v2/locations |
listLocations | List the seller's business locations |
| POST | /v2/team-members/search |
searchTeamMembers | Search team members (staff) |
| GET | /v2/bookings/business-booking-profile |
retrieveBusinessBookingProfile | Get the seller's booking settings |
| GET | /v2/bookings/team-member-booking-profiles |
listTeamMemberBookingProfiles | List staff who can be booked |
| POST | /v2/bookings/availability/search |
searchAvailability | Find open appointment slots |
| GET | /v2/bookings |
listBookings | List appointments |
| POST | /v2/bookings |
createBooking | Book an appointment |
| GET | /v2/bookings/{booking_id} |
retrieveBooking | Get one appointment |
| PUT | /v2/bookings/{booking_id} |
updateBooking | Reschedule or update an appointment |
| POST | /v2/bookings/{booking_id}/cancel |
cancelBooking | Cancel an appointment |
| POST | /v2/catalog/search |
searchCatalogObjects | Search services, items and prices in the catalog |
| GET | /v2/catalog/object/{object_id} |
retrieveCatalogObject | Get one catalog item or service |
| POST | /v2/inventory/counts/batch-retrieve |
batchRetrieveInventoryCounts | Check stock levels |
| POST | /v2/customers/search |
searchCustomers | Search customers by phone, email or name |
| GET | /v2/customers/{customer_id} |
retrieveCustomer | Get one customer |
| POST | /v2/customers |
createCustomer | Create a customer profile |
| POST | /v2/orders/search |
searchOrders | Search orders |
| GET | /v2/orders/{order_id} |
retrieveOrder | Get one order |
Authentication
squareAccessToken
Bearer token — sent as Authorization: Bearer <token>
Square access token, sent as Authorization: Bearer <token>.
How to get a token
- Sign in at developer.squareup.com and create an application.
- Open the app → Credentials. Copy the Production access token (personal token for your own Square account).
- Testing first? Use the Sandbox token with a sandbox copy of this spec whose base URL is
https://connect.squareupsandbox.com— production tokens do not work in the sandbox and vice versa. - Store the token as a credential in VX Agents so the model never sees it.
Permissions used
| Area | Operations |
|---|---|
| Locations, team | listLocations, searchTeamMembers |
| Appointments | searchAvailability, listBookings, retrieveBooking, createBooking, updateBooking, cancelBooking, retrieveBusinessBookingProfile, listTeamMemberBookingProfiles |
| Catalog, inventory | searchCatalogObjects, retrieveCatalogObject, batchRetrieveInventoryCounts |
| Customers | searchCustomers, retrieveCustomer, createCustomer |
| Orders | searchOrders, retrieveOrder |
A personal access token has full access to your account. For a client's account, use Square OAuth with only the permissions above (APPOINTMENTS_READ/WRITE, ITEMS_READ, INVENTORY_READ, CUSTOMERS_READ/WRITE, ORDERS_READ, MERCHANT_PROFILE_READ, EMPLOYEES_READ).
Common errors
- 401 UNAUTHORIZED – wrong or revoked token, or a sandbox token on production.
- 403 INSUFFICIENT_SCOPES – the OAuth token lacks a permission listed above.
- 400 INVALID_REQUEST_ERROR – check the
errors[].fieldin the response.
Usage guide
Setup
- Connect this spec to an agent and add your Square access token as the credential (see Authentication).
- Call
listLocationsonce and pin thelocation_idof the shop as a preset parameter, so the agent never books at the wrong branch.
Booking an appointment
searchCatalogObjectswithobject_types: ["ITEM"]to find the service and its service variation id andversion.listTeamMemberBookingProfilesto see which staff can be booked (optional: let the customer choose).searchAvailabilitywith the location, service variation and a date range (at most 31 days) to get open slots.searchCustomersby phone or email;createCustomeronly if nobody matches.- Confirm service, staff, time and customer with the customer, then
createBookingwith the slot'sstart_at,appointment_segmentsandcustomer_id.
Reschedule with updateBooking (send the current version), cancel with cancelBooking. Both should be confirmed with the customer first.
Shop questions
- Prices and services:
searchCatalogObjects/retrieveCatalogObject. - Stock:
batchRetrieveInventoryCountswith catalog object ids (and the location id). - Order status:
searchOrdersby location and customer, thenretrieveOrder.
Good to know
- Times are RFC 3339 in UTC (
2026-10-12T09:00:00Z); convert from the shop's local time zone (listLocationsreturns it). - Seller-level booking rules (cancellation window, who may book) come from
retrieveBusinessBookingProfile. - Bookings created through the API require the seller to have Square Appointments enabled.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Square Appointments, Catalog & Orders” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.