Request for API Rate Limit Review / Increase

Questions
, , ,
1

Hello Square Team,

We would like to discuss the API rate limits for our integration and seek your guidance on possible solutions.

Our Business Scenario

We support a merchant organization that currently operates more than 30 store locations under the same Square account.

During promotional events, traffic can increase significantly:

  • Approximately 20 orders per second per location at peak times

  • More than 30 locations participating simultaneously

  • Peak order volume may therefore exceed 600 orders per second across the organization

Webhook-Driven API Activity

In addition to our direct API requests, we subscribe to multiple Square webhooks, including:

  • Orders Webhooks

  • Catalog Webhooks

  • Loyalty Webhooks

When these webhooks are received, our platform performs additional Square API calls to synchronize and enrich data, including:

  • Order retrieval and updates

  • Catalog lookups

  • Loyalty account queries and updates

  • Customer-related data synchronization

As a result, a single business event may trigger multiple follow-up API requests.

Current Challenge

During high-volume promotional campaigns, we frequently encounter API rate limit responses (HTTP 429).

These rate limits impact:

  • Order synchronization latency

  • Loyalty processing

  • Inventory/catalog synchronization

  • Overall customer experience

Request

Could you please help us understand:

  1. Which specific API endpoints are most likely contributing to the rate limiting?

  2. Whether higher rate limits are available for enterprise-scale merchants with this traffic profile?

  3. Whether Square offers:

    • Custom rate limit increases

    • Organization-level quota adjustments

    • Best practices for webhook-driven architectures at this scale

  4. Any recommendations for reducing API consumption while maintaining near real-time synchronization.

Additional Information

We would be happy to provide:

  • Endpoint-level request statistics

  • API usage metrics

  • 429 response logs

  • Merchant and application identifiers

Thank you for your assistance. We look forward to your recommendations.

Best regards,

Murphy

3

Hi Murphy,

Thanks for the detailed write-up. Looking at your setup there are some clear optimization opportunities that should help significantly:

Catalog webhooks are likely your biggest culprit. catalog.version.updated fires from all sources (Dashboard, POS, other integrations) and only contains a timestamp, but not what changed.

Suggestions:

  • Cache the updated_at timestamp from each webhook event

  • On the next event, callSearchCatalogObjects with the previous timestamp as begin_time to return only what changed in that window

  • Scope your search to only the object_types you care about (e.g.,ITEM,ITEM_VARIATION) to reduce response size

  • Avoid calling ListCatalog on every event as the result set can be very large and will accelerate rate limiting.

More detail in our catalog sync guide.

Other suggestions:

  • Use batch endpoints when possible (BatchRetrieveOrders,BatchRetrieveCatalogObjects, etc.)

  • Deduplicate by event_id to avoid processing the same webhook twice

  • Filter out self-triggered webhook events (your own writes firing webhooks back at you)

  • Defer non-critical syncs to off-peak hours

For handling 429s gracefully when they do occur: Handling Rate Limiting Errors

Happy to answer any follow-ups!

4

Hello Square Team,

Thank you for your previous explanation regarding our webhook implementation.

We understand that some of our current webhook-driven API calls may not align with Square’s recommended architecture, and we are reviewing those areas.

However, we would like to better understand the recommended approach for handling high-volume order traffic.

Our Scenario

We support a merchant organization with more than 30 locations.

During promotional campaigns, individual locations may experience up to 20 orders per second, resulting in hundreds of orders per second across the merchant organization.

Even if we optimize our webhook processing and eliminate unnecessary API calls, we still need to:

  • Process order events in near real time

  • Synchronize customer and loyalty information

  • Update internal systems based on Square events

  • Maintain operational visibility during peak traffic periods

Questions

Could you please clarify Square’s recommended architecture for merchants operating at this scale?

Specifically:

  1. For high-volume order creation and updates, should webhook payloads be treated as the primary source of truth whenever possible, instead of calling RetrieveOrder APIs?

  2. Are there recommended patterns for processing Orders, Catalog, and Loyalty webhooks at scale?

    • Event queueing?

    • Delayed reconciliation?

    • Periodic batch synchronization?

  3. If a merchant is generating hundreds of order events per second, what is the expected strategy for maintaining data consistency without exceeding API limits?

  4. Does Square provide any guidance regarding:

    • Event-driven architectures

    • Queue-based processing

    • Bulk synchronization approaches

    • Recommended polling frequencies

  5. Are there specific APIs that should be avoided in real-time processing paths due to rate-limit considerations?

  6. For enterprise merchants with sustained high transaction volumes, are there alternative quota models or traffic-management recommendations available?

Goal

Our objective is to align our integration with Square’s recommended best practices while maintaining near real-time synchronization for large-scale merchants.

Any architectural guidance, documentation, or reference implementations would be greatly appreciated.

Thank you for your assistance.

Best regards,

murphy