It works at the first location and returns an auth error at the other four

The code is the same at every restaurant, so the difference is not in the code. POS platforms almost always issue access per merchant location rather than per brand or per company, and the grant is performed by whoever administers that location — often the individual owner or manager, not the group's head office. One store working and 4 failing usually means the authorisation flow was completed once, in a meeting, on a laptop, at 1 restaurant.

This is a commercial and operational shape rather than an engineering one, which is why it survives good code review. The platform is protecting a merchant's data from an integrator the merchant did not personally approve. That is the right behaviour, and the scope of what a platform will let you do once approved is a separate question, covered in what a POS partner programme actually gates.

The credential inventory almost nobody has built

Before diagnosing anything, build the table. It takes an afternoon, it is the artefact that makes every future instance of this a 30-second question, and its absence is why teams debug this by reading application logs at 8pm on a Friday.

Four stores that were never actually authorised

The commonest cause is the dullest. Somebody clicked through the authorisation flow at the pilot restaurant, the integration went live, and the remaining locations were listed in a project plan as "same setup". Nobody performed the grant, because the grant is a human action on a screen in the merchant's own admin, and it produces no artefact anywhere in your system when it does not happen.

The tell is in the inventory: a row with no grant timestamp. If you have not built the inventory yet, the equivalent check is to ask the platform which locations your application currently holds a grant for, rather than asking your own database what you think you were given. The full sequence from developer account to a live restaurant is set out in from a developer account to a live restaurant.

Scopes granted unevenly, and the error that will not say so

Authorisation screens change. A location authorised in March may hold a scope set that no longer matches what your application requests today, and a location authorised last week may hold more. Where a merchant admin can approve a subset of what you asked for, they will sometimes do so — usually declining the write permissions, which are the ones that matter.

• Record the granted scopes, not the requested ones. The 2 lists differ silently, and only the first is true.
• Test each scope at go-live rather than trusting the grant. A read that succeeds proves nothing about the write you need during service.
• Expect reads to outlive writes. Menu sync working while order injection fails at 1 store is the classic signature, and it is why the symptom often surfaces during the first real order rather than in testing — the same asymmetry that makes the full menu sync that never finishes a separate problem from writing checks.
• Do not paper over a missing scope with a fallback. Silently degrading to a mode the restaurant did not ask for is worse than failing loudly at 3pm.

A location id in the slot where a merchant id belongs

Multi-location platforms carry at least 2 identifiers: something that identifies the business and something that identifies the individual restaurant. They are frequently similar-looking opaque strings, and the pilot store is often the one where both resolve to the same thing, which is precisely why the bug survives the pilot.

Store both, in named columns, and never derive one from the other. The same discipline applies to every identifier you hold on the platform's behalf — the argument in the mapping table between your ids and the POS — and it is the reason your test orders sometimes land in a real restaurant's figures, as in your test orders are now in the owner's sales report.

The refresh token you rotated and did not persist

Many platforms rotate refresh tokens: each refresh returns a new refresh token and invalidates the old one. If your process crashes between receiving the new token and committing it, or if 2 workers refresh the same credential concurrently, one of them writes a token the platform has already retired. Nothing errors at that moment. The location simply stops working at the next refresh, hours later.

1. Refresh proactively on a schedule, well before expiry, rather than reactively on the first 401 during a dinner service.
2. Serialise refreshes per location with a lock, so 2 workers cannot both spend the same single-use refresh token.
3. Commit the new token in the same transaction that marks the refresh complete, and keep the previous value for 1 cycle so a failed write is recoverable.
4. Log every refresh with its outcome. A rotation failure is invisible in application logs that only record request errors.
5. Treat re-authorisation as a supported operational path, not an incident: a one-click flow the restaurant's manager can complete without you, because eventually one of them will have to.

The owner revoked you from a screen you have never seen

Merchant admin consoles list connected applications with a disconnect button next to each, and restaurants use it: during a POS upgrade, when a franchisee changes hands, when a manager is tidying up, when a different vendor is being trialled. You will usually not be told, and there is often no callback to your system when it happens.

This is also why credential ownership should be settled in writing before launch — whose developer account, whose grant, what happens when the person who clicked through leaves — the subject of whose POS credentials are these. And it is a live risk during any POS change, which is why switching POS without taking ordering down treats re-authorisation as a scheduled step rather than a surprise.

Alert on silence, because a dead location produces no errors

Error-rate alerting misses this entirely. A location whose grant was revoked, or whose token expired between services, stops making calls — and zero calls generates zero errors. The monitor that works is a per-location heartbeat: expected activity in a window, measured against what the location actually did.

A restaurant that has stopped calling you looks identical to a restaurant that is quiet. Only the calendar knows the difference, which is why the alert has to be built on expected traffic rather than on failures.

Set the window from each location's own trading pattern rather than a global default — a site open 7 days is not a site open 5 — and route the alert to whoever can ask the restaurant to re-authorise, which is usually account management rather than engineering. That per-location asymmetry is the same reason configuration drifts across a group, as it does with tables as sellable inventory, and building the inventory, the heartbeat and the re-authorisation flow is ordinary internal tools and ops work.

One thing this page deliberately does not cover: how to roll an integration out across dozens of sites, in what order, with what sign-off. That is governance rather than diagnosis. Missed status changes during service are their own failure, handled in the POS says it sent the event and your system never moved. The rest of this silo sits under integrating with the POS on the counter, inside our restaurants and food service practice.

• pos
• oauth
• multi-location
• diagnostics