POS integrations overview
How stores, terminals and point-of-sale systems connect to MyNearStores.
Connecting a point-of-sale (POS) system lets a store validate MyNearStores redemptions at the register, sync sales, and give members a digital receipt. Merchants connect their POS from the merchant dashboard. Partners building their own register or kiosk software call the same endpoints directly.
Concepts
| Term | Identifier | Meaning |
|---|---|---|
| Business unit | bu_id | The merchant account in MyNearStores. |
| Store | store_id | One physical location of the business unit. |
| Terminal | terminal_id | A register, tablet or kiosk at a store. POS connections are per terminal. |
A business unit with three stores and two registers per store has six terminals. Each terminal can be linked to its own Square or Lightspeed account.
How the pieces fit
Register the terminal with the terminals API, or in the dashboard.
Connect the POS. The merchant approves access in a popup: Square or Lightspeed. The OAuth token is stored against that terminal.
Sell as usual. Square and Lightspeed push payment and sale events to MyNearStores through webhooks, and MyNearStores can record sales in Square.
Redeem offers. When a shopper's MyNearStores QR code is scanned, the terminal opens a QR redemption session, validates it, and marks it used.
Send the receipt. Members get a digital receipt link for Lightspeed sales.
Calling the API
All endpoints are on the jsserver origin you receive during onboarding (the examples use $MNS_API). Requests and responses are JSON unless noted.
export MNS_API="https://<jsserver origin from onboarding>"
curl "$MNS_API/square/oauth/status/1/31"Keep these calls on your server
The POS endpoints identify a business and terminal by their numeric IDs and do not take an API key or bearer token today. Call them from your backend, not from shopper-facing browser code, and treat bu_id and terminal_id values as confidential.
Integrations
| POS | Connect | Data MyNearStores receives | Data MyNearStores sends |
|---|---|---|---|
| Square | OAuth, per terminal | payment.created, completed payment.updated | Orders and payments (Sales reports) |
| Lightspeed Retail (X-Series) | OAuth, per terminal | Sales, sale customer changes, inventory | Digital receipts for members |
The API reference lists every endpoint, parameter and response.