Skip to main content
The first rule is simple: if a Production payment is pending or uncertain, do not send it again. Reconcile the existing checkout before changing settings, stock, device, or Storefront configuration.

​
Start here

​
Five-minute operator triage

  1. Record the workspace, environment, location, Terminal name, order reference, time, timezone, amount, currency, and visible status.
  2. Stop submitting new checkouts for the affected order.
  3. Compare Payments → Test & verify with the matching Square Dashboard.
  4. If Square shows a completed payment, treat it as paid and reconcile it.
  5. If Square proves no payment and the Terminal checkout is pending, cancel the same checkout or allow it to expire.
  6. Verify the reservation and stock after the final event.
  7. Escalate with IDs, timestamps, and redacted screenshots if the systems still disagree.

​
Connection and readiness

This is expected for an unconfigured environment. Select Production, enable editing, save the Production application credentials, connect the real seller through OAuth, add the Production webhook signature key, choose the location, and pair the Terminal. Do not copy the Sandbox token.
Save the Square Application ID and Application secret for the selected environment first. Copy the OAuth redirect URL from Inventory into that environment’s Square application settings. Confirm the URL matches exactly.
The access token commonly belongs to the other environment, was revoked, or lacks a required scope. Confirm the environment badge, seller, and application. Re-authorize the intended seller instead of adding unrelated manual tokens.
Verify the OAuth seller and MERCHANT_PROFILE_READ permission. A location cannot be borrowed from another seller or from Sandbox. Reconnect the correct account, refresh locations, and ask the Square owner to confirm the location name.
Square sends oauth.authorization.revoked, and Tuturuuu marks the connection unavailable. Stop checkouts, ask the owner why access was revoked, then re-authorize only if the owner approves it.

​
Webhooks

Confirm the subscription environment, notification URL, signature key, and event type. Copy the workspace webhook URL from Inventory; do not rebuild it manually. The exact URL used by Square is part of signature verification.
Square signs the configured notification URL plus the raw body. Update the Square subscription and Inventory’s advanced notification URL to the same exact HTTPS value, then replace the matching environment’s signature key.
Duplicate delivery is normal when an acknowledgement is delayed or Square retries. Compare the event_id. Tuturuuu should keep one checkout, payment, stock transition, and finance entry. Escalate only if business state is duplicated.
Square does not guarantee delivery order. Reconcile by provider object and final payment status rather than arrival time. Do not edit checkout state manually to match the first event you saw.
Square may not emit inventory.count.updated when the written count equals the existing value. In Sandbox, change the demo count to a distinct value, verify the event, then restore it intentionally.

​
Terminal and pairing

A phone or tablet running Square POS with a connected Reader is not a Terminal API device. It will not appear after Refresh terminals. Select Phone or tablet with Reader, register the POS callback URL, and use the Square POS app + Reader Storefront mode instead.

​
Square POS app and Reader

The Point of Sale API callback is not treated as payment proof by itself. Tuturuuu uses the returned transaction ID as a Square Order ID, retrieves its Payment, and verifies the exact reserved amount, currency, location, completed status, and card tender. This is why cash and offline returns are not automatically finalized. Square Terminal cannot use browser-based captive-portal networks. Review Square’s network requirements and Terminal network troubleshooting.

​
Checkout, payment, and stock

Keep the same order. Check Square Payments and the Terminal checkout. If no payment completed, cancel that checkout from Inventory Commerce or let it expire. Tuturuuu reservations expire after 15 minutes and release stock when final reconciliation runs.
Search Square by location, time, amount, and receipt. If Square shows a completed payment, do not retry. Record the Square evidence and inspect the payment.updated and terminal.checkout.updated webhook deliveries.
Confirm you are viewing the same Sandbox or Production seller and location. Record all evidence and stop new attempts. This mismatch requires support investigation; do not create a balancing payment or manual stock change.
Refresh the Commerce and Payments views after the final Square event. Allow the scheduled expiry reconciliation to run. If the reservation remains, escalate with the order reference, final Square status, timestamps, and stock values. Do not compensate by increasing on-hand stock manually.
Stop processing the item, preserve the rows, and compare Square event IDs and provider IDs. Duplicate webhooks must be idempotent. Do not delete a duplicate-looking record before support confirms which row is authoritative.

​
Catalog and stock sync

Open the Linked catalog records list, clear any UI filter, and verify the environment. Metrics count item, variation, and stock operations, so the total can exceed the number of unique products. One visible link row is the reliable evidence for one Square variation relationship.
Stop all sync and checkout actions for that item. Record the human-readable amount and currency on both sides. Do not manually multiply or divide and sync again. Confirm the current Tuturuuu release, then correct the approved source once and verify a one-way sync with a demo item first.
This is protective behavior. Compare the Tuturuuu and Square values, get an owner decision, and run one directional sync from the approved source. Do not alternate directions or delete the Square item.
Tuturuuu intentionally keeps the local product and link for review. Ask the owner whether to republish the item or leave it disconnected. Synchronization never deletes Square objects or local product data to resolve this status.

​
Storefront issues

​
Never do these during an incident

  • Do not send the same Production order again while the first is pending or uncertain.
  • Do not create a second charge to cancel out an uncertain charge.
  • Do not copy Sandbox tokens, IDs, device simulators, or webhook keys into Production.
  • Do not delete or archive Square catalog objects to force synchronization.
  • Do not manually increase stock while an unresolved reservation exists.
  • Do not paste secrets or customer personal data into an escalation message.
  • Do not factory-reset a Terminal until the Square owner understands the impact and the current checkout has been reconciled.

​
Escalate with evidence

Include the packet from the operations guide and check Square system status for provider-wide incidents. Redact tokens, application secrets, signature keys, full card data, and customer personal information. For implementation-level failures, use the Square Terminal engineering runbook.