Rate limits for a multi-tenant OAuth app — how do they scale with connected merchants

Questions
,
1

Hi everyone,

I’m building a multi-tenant online booking widget for Square Appointments (Next.js app, one Square OAuth application, many independent merchants each connect their own Square account via Authorization Code + PKCE — no APPLICATION_SECRET stored anywhere, per Square’s recommended public-client flow). Each merchant gets their own booking page; the widget calls Locations, Catalog, TeamMemberBookingProfiles, BusinessBookingProfile, SearchAvailability, and CreateBooking on the merchant’s behalf using their access token.

Scopes requested: APPOINTMENTS_READ, APPOINTMENTS_ALL_WRITE, APPOINTMENTS_WRITE, APPOINTMENTS_ALL_READ, APPOINTMENTS_BUSINESS_SETTINGS_READ, CUSTOMERS_READ, CUSTOMERS_WRITE, PAYMENTS_READ, PAYMENTS_WRITE, MERCHANT_PROFILE_READ.

We recently hit:

Status 429
{ "errors": [{ "category": "RATE_LIMIT_ERROR", "code": "RATE_LIMITED",
  "detail": "Application is rate limited, please try again in a few minutes" }] }

during a burst of concurrent testing across a handful of connected merchants — this looked like an application-wide limit, not a per-merchant-token one.

A few questions as we plan for growth (currently a handful of merchants, aiming for hundreds):

  1. Are rate limits enforced per application (aggregated across every connected merchant’s calls) or per individual access token? The error message and our own logs suggest application-wide, but I’d like to confirm.
  2. What’s the process to request a limit increase for a growing app — is there a form, or should we go through Developer Support directly?
  3. Any official guidance for multi-tenant platforms on staying under these limits at scale (e.g., recommended caching windows for Locations/Catalog, batching patterns, or a documented backoff strategy Square expects clients to implement)?

Thanks in advance — happy to share more detail about our usage pattern if it helps.

2

It sounds like you’re hitting an application-wide rate limit. I’d recommend adding caching, reducing unnecessary API calls, and using exponential backoff for retries. For higher traffic, contact Square Developer Support to confirm the limits and discuss a possible increase.

3

Correct, rate limits are at the application level and may vary by endpoint. Handling Errors