Square - Developer Platform for Commerce APIs

Square's developer platform gives you APIs to integrate with their payment ecosystem - everything from processing credit cards to managing inventory and customer data. It's built around their existing point-of-sale business, which means you get access to unified commerce APIs that work both online and in physical stores.

The core offering includes 20+ REST APIs covering payments, catalog management, customer data, bookings, team management, and inventory tracking. You also get SDKs for 7 languages, plus specialized tools like the Web Payments SDK for browser integration and Terminal API for hardware integration.

The reality check: Square's APIs don't suck as much as PayPal's disaster of a platform, but they're not as polished as Stripe's developer experience either. You can get basic payment processing working in an afternoon, but expect to hit undocumented quirks when you need anything beyond vanilla transactions.

Rate limits are completely undocumented. You'll randomly hit 429 errors and Square just tells you to "use exponential backoff" without saying what the actual limits are. I've spent 6 hours straight debugging why my integration randomly fails because their error messages are about as helpful as a screen door on a submarine.

Recent Platform Updates

Square's been pushing hard on mobile payments lately. In February 2025, they released Mobile Payments SDK GA and new Terminal API features, expanding their in-person payment capabilities. The Web Payments SDK now requires Secure Contexts starting October 2025, which broke a bunch of existing integrations without proper warning.

Their API versioning system uses date-based versions like 2024-10-17 and maintains decent backward compatibility. The developer dashboard provides API logs for debugging, though you'll still end up digging through the community forums to understand why your webhook suddenly stopped firing.

What Makes Square Different

Square's strength is unified commerce. If you need to sync inventory between an online store and physical locations, or want customers to start purchases online and complete them in-store, Square's APIs actually handle this well. Most payment platforms treat online and offline as separate worlds.

The Catalog API and Inventory API are surprisingly robust. You can manage complex product variations, track inventory across multiple locations, and handle things like combo meals or service appointments. Their Orders API ties everything together, letting you create orders that span multiple channels.

But here's the catch - if you're building a pure online business, Stripe's APIs are cleaner and more flexible. Square shines when you need that omnichannel integration with physical retail locations.

OAuth and Authentication Headaches

OAuth works fine until your tokens expire and you get cryptic 401s. I spent 3 hours debugging this because Square's error messages don't tell you which token is expired. The refresh token flow is standard, but their error responses are about as informative as a Magic 8-Ball.

Pro tip: set up automatic token refresh before you need it, not after your integration breaks in production at 2 AM on a Sunday.

The sandbox environment uses different OAuth flows than production, which isn't clearly documented. Your test tokens work perfectly in development, then fail mysteriously when you deploy because the production OAuth endpoint has different requirements.

Rate Limiting: The Undocumented Pain

Square doesn't publish their rate limits, which is insane for a 2025 API. During load testing our Node.js app in October 2024, we started hitting limits around 847 requests/minute on the Payments API, but the Catalog API was much lower at ~200/minute.

When you hit a 429 error, Square gives you a generic "use exponential backoff" message without telling you what the actual limits are or how long to wait. I've seen rate limits vary by endpoint, time of day, and what appears to be random API server selection.

The official error handling docs recommend exponential backoff but provide zero specifics about timing or limits. You'll end up implementing retry logic through trial and error.

Webhook Reliability Issues

Webhooks work most of the time, but they're not as reliable as Stripe's. During our Black Friday integration in 2024, we had webhooks just stop firing for 6 hours - no explanation, no error, just silence. Always implement polling as a backup because webhooks can and will fail at the worst possible time.

The webhook signature verification works fine when it works, but we've seen intermittent signature mismatches that resolve themselves after a few hours. Square's webhook troubleshooting docs are basic and don't cover the weird edge cases you'll encounter in production.

Geographic and Currency Limitations

Square's international support is laughably limited compared to Stripe. As of August 2025, they support about 10 countries while Stripe handles 40+. If you need to process payments in Brazil, India, or most of Europe, you're out of luck.

UK transactions randomly failed for 3 weeks in March 2024 because Square's fraud detection got overzealous, and their support took 5 days to acknowledge the issue existed. Test everything twice if you're outside North America.

Currency support is basic - USD, CAD, GBP, EUR, JPY, and AUD. That's it. No emerging market currencies, no crypto payments, no alternative payment methods that aren't credit cards or bank transfers.

Error Messages That Make You Want to Scream

Square's error messages are frustratingly vague. Instead of "Payment failed: card declined by issuer", you get GENERIC_DECLINE with no additional context. Their error codes include gems like:

• GENERIC_DECLINE (thanks, very helpful)
• PAYMENT_PROCESSING_ERROR (could be anything)
• INVALID_REQUEST_ERROR (what part of the request?)

Compare this to Stripe's detailed error responses that actually help you fix the problem. Square's errors require you to guess what went wrong and implement defensive coding for every possible failure mode.

The Good Parts (Yes, There Are Some)

When Square's APIs work, they work well. The unified inventory system across online and physical stores actually delivers on its promise. We can update product availability from our warehouse system and it instantly reflects in both our web store and physical POS terminals.

The Terminal API for hardware integration is solid once you get it configured. Square's POS hardware ecosystem just works together without the integration headaches you get trying to connect different vendors' systems.

Orders API handles complex scenarios well - partial payments, split tenders, refunds, and modifications all work as expected. The catalog system properly handles product variations, combo items, and service appointments without breaking down.