Skip to main content
The LoyaltyDog Square integration connects a Square merchant account to your LoyaltyDog loyalty program via OAuth, awards points on completed sales, and — for merchants using a LoyaltyDog kiosk device — lets a cashier apply a points discount directly at checkout.

​
What it does

  • Awards loyalty points automatically when a Square sale completes, looking up or enrolling the LoyaltyDog customer from the Square customer profile.
  • Lets a customer without an attached profile at checkout claim their points afterward by scanning a QR code on their receipt.
  • Runs points-discount checkouts from a LoyaltyDog kiosk device: a cashier looks up the customer, previews the discount, and commits it either straight to a Square Terminal reader or as a parked Square order the cashier rings up manually.
  • Mirrors location, customer, and order changes from Square via webhooks (customer sync, payment/order updates, OAuth revocation).

​
Install

Square uses an OAuth connection, not an App Marketplace install.
  1. In the LoyaltyDog dashboard, go to Loyalty → Square and select Connect Square.
  2. You’re redirected to Square to authorize LoyaltyDog for your merchant account. Approving the request returns you to the dashboard with your Square locations listed.
  3. For each Square location you want to sync, link it to a LoyaltyDog program from the location picker. A multi-location merchant can map each location to its own program, or all locations to one program.
Square fixes the requested scopes at authorization time — if LoyaltyDog later needs a scope your connection doesn’t have (for example, when kiosk checkout is enabled on a location for the first time), the dashboard prompts you to reconnect.

​
Kiosk device management

A LoyaltyDog kiosk is a device at the register that a cashier uses to apply points discounts. Kiosks have no login of their own — they pair with a one-time code generated from the dashboard.
  1. From Loyalty → Square → [location] → Devices, select Add device and give it a name. The dashboard mints a short-lived (15-minute) one-time pairing code.
  2. On the kiosk device, enter the pairing code. It’s exchanged for a long-lived device token the kiosk uses for all subsequent checkout calls — the plaintext code is shown once and can’t be retrieved again.
  3. To decommission a device — it’s lost, retired, or you suspect its token leaked — select Revoke next to the device in the dashboard. Revocation immediately invalidates the device’s token; a revoked device must be paired again with a new code to resume checkouts.
Device pairing and revocation are dashboard actions (not endpoints third-party tools call directly) — there’s no merchant-facing REST API for device management.

​
Checkout modes

Each linked Square location has a checkout mode that determines how a kiosk-committed points discount reaches Square: Set the mode per location from Loyalty → Square → [location] → Checkout mode in the dashboard. A location with no mode set falls back to whatever mode the kiosk requests, for backward compatibility with connections made before checkout modes existed.

​
Claim and checkout endpoints

The following endpoints are called by the LoyaltyDog QR-claim page and by kiosk devices — not typically by third-party integrators — but are documented here for completeness.

​
QR claim (no attached customer at checkout)

When a Square sale completes without a customer attached, LoyaltyDog creates a pending claim instead of awarding points immediately. The receipt includes a QR code that lets the customer claim their points afterward. GET /v2/square/pos/claim/lookup/{claim_token} returns the merchant and order metadata for a claim token. It responds 200 for a valid, unclaimed token, 410 once the claim has expired or already been claimed, and 404 for an unknown token. POST /v2/square/pos/claim/submit awards the points and consumes the claim, given the claimToken plus a contactType (email or phone) and contactValue to identify or enroll the customer:
It responds 410 if the claim was already consumed or has expired, 404 for an unknown token, and 422 if the supplied contact can’t be validated as an email or phone number.

​
Kiosk checkout pipeline

Kiosk devices authenticate with the device token minted during pairing (see Kiosk device management). A checkout runs in three steps:
  1. POST /v2/square/pos/lookup_customer — find or enroll the customer by email or phone, returning their points balance and available (unreserved) balance.
  2. POST /v2/square/pos/preview_order — given a customerId and the basket, LoyaltyDog computes the discount server-side against the program’s active price rule and puts a short-lived (5-minute) hold on the points. The client never supplies the discount amount.
  3. POST /v2/square/pos/commit_checkout — consumes the preview exactly once and creates the Square order with the discount applied, then dispatches it per the location’s checkout mode: pushed to a Terminal reader, or parked as an open order for the cashier to ring up.
GET /v2/square/pos/checkout_status/{our_checkout_id} polls a checkout’s lifecycle status (pending, sent, completed, failed, canceled), scoped to the requesting device.

​
Troubleshooting

  • Sales aren’t producing points — Check that the Square location is linked to a LoyaltyDog program in the dashboard, and that the sale had a customer attached at checkout (otherwise it becomes a QR claim instead of an immediate award).
  • Customer never got their points from a QR claim — Claims expire; if the customer scanned the receipt after the expiry window, GET /v2/square/pos/claim/lookup/{claim_token} returns 410 and they’ll need to contact support instead.
  • Kiosk can’t apply a discount / “terminal device unconfigured” — The location’s checkout mode is set to Terminal API but the kiosk has no Terminal reader paired. Either pair a reader or switch the location to Open ticket mode.
  • Kiosk checkout is rejected outright — The location’s checkout mode is set to Disabled, or the Square connection is missing a required write scope (reconnect from the dashboard to re-grant it).
  • Device stopped working after being revoked — Revocation is immediate and irreversible for the old token; pair the device again with a new one-time code from the dashboard.
Multiple Square locations can map to the same LoyaltyDog program, or each to its own program — the choice is yours.