Preventing overselling of the last item across a custom website and Square POS

Questions
1

I’m building a website that sends orders and payments to merchants’ Square accounts.

In a sandbox test, I started with one item in stock. Another Square API purchase bought it after our website’s stock check but before our website completed payment. Both payments succeeded, leaving inventory at −1.

Does Square offer an API-supported reservation or checkout mechanism that prevents this across a custom website and Square POS? I noticed RESERVED_FOR_SALE is read-only through the Inventory API.

If so, which endpoints and merchant settings should we use? If not, what approach does Square recommend for integrations?

4

Welcome to the Developer Forum!

Your test shows a check-then-pay race. Square does not document an API operation that reserves the last unit against both your website and Square POS; the Inventory API cannot move stock into RESERVED_FOR_SALE.

You can enable inventory tracking and automatic sold-out status for the relevant variations and locations, check availability right before taking payments, and use inventory/catalog webhooks to update your site. However, these measures reduce stale availability but cannot really guarantee that another sale won’t complete first. I suggest you reconcile completed sales and have an out-of-stock/refund process.