A WooCommerce and Square sync that has to be right, because it moves real stock and real money.

Plenty of businesses sell in a shop through Square and online through WooCommerce. The two systems each think they own the stock count. Sell the last bag of coffee at the counter and the website will happily sell it again unless something tells it, quickly and correctly.

The obvious fixes break in boring ways. Square webhooks go missing when a site is slow or a host blocks the request. WP cron only runs when someone visits. Square rate limits bulk work. And every sync that writes back risks an echo: a Woo edit goes to Square, Square fires a webhook, and the change comes straight back as a second update or, worse, a duplicate order.

A WordPress plugin with a React admin app inside wp-admin and a PHP backend built on Action Scheduler queues, plus the services it depends on. Merchants choose which fields each side owns, and the plugin enforces that ownership on every import, export and webhook.

Most of the work is in the failures that make no noise. A stock push that quietly does nothing, a gift card charged as a $0 payment, a product imported twice by two queue workers at once. Each looks like success in a naive log. I treat every one of those as a test: 51 integration suites run inside a real WordPress install with Square faked at the HTTP layer, so they assert on exactly what would have been sent to Square, not just on what WooCommerce ended up with.

Some concrete examples. Loop guards and push markers stop an order the site created in Square from being imported back as a second order. A cross-process lock per Square item means parallel workers never create the same product twice. Square's order search is cursor-paginated with no total, so the orders screen keeps pulling pages until a filtered view is genuinely full. And when Square rejects something, the log does not just show the error code: it records a plain-English cause and fix at the moment it happens, written only for errors I have actually diagnosed.

Square sends each event once. If a customer's site is down, slow or behind a firewall, that update is gone, and the shop drifts out of sync with nothing to show for it. So the plugin does not take webhooks from Square directly. My relay takes them, verifies the signature, stores them in PostgreSQL and delivers them through BullMQ with a per-site circuit breaker.

When a site fails three times in a row the circuit opens and retries back off at 1, 5, 15 and 60 minutes. Held events are kept rather than dropped, and replayed oldest first (up to 500 at a time) once the site responds. A fair scheduler stops one busy merchant starving everyone else, and stores running several sites are isolated by callback URL. Inside the plugin, merchants see all of this as one plain verdict, with the controls to test, resume or discard a backlog themselves instead of opening a ticket.