Square POS Integration Setup
Connecting Square's POS with ReceiptRoller automatically sends transaction data at checkout, generating a digital receipt. The connection is completed with just Square account authentication. No Square developer settings or API key entry is required.
Step 1: Open the POS Terminals screen
Click "POS Terminals" from the feature card list on the store dashboard. The POS terminal list screen opens.
Step 2: Connect with Square
Click the "Connect with Square" button in the upper right of the screen. You'll be taken to Square's authentication page.
Step 3: Authenticate with your Square account
Sign in to your Square account on Square's login screen, review the access permissions, and click "Allow." Once authentication completes, you'll automatically return to ReceiptRoller.
Step 4: Select a location (if you have multiple locations)
If your Square account has multiple locations (stores/branches) registered, the "Select Square Location" screen is displayed. Click "Select this location" for the location that corresponds to the store you're connecting.
If there is only one location, this screen is skipped and the connection completes automatically.
Checking after the connection is complete
"Connected with Square" is displayed in the POS terminal list, and a new terminal card is added. The card displays the following information.
- Terminal name (e.g., Square POS — Store Name)
- Square badge and API integration badge
- Location (address)
- Number of synced transactions
- Status (Active)
Data synced after connecting
Once connected, the following data flows automatically between Square and ReceiptRoller.
| Data type | Direction | Timing | Details |
|---|---|---|---|
| Transactions (line items, amounts, payment method) | Square → RR | Real time (webhook) | Square Transaction Data Mapping |
| Customer information (name, contact info, member number, birthday, address) | Bidirectional | Within seconds of registration/update, plus hourly differential sync | Bidirectional Member Data Sync / Customer Data Mapping |
| Product master (name, SKU, category, price) | Square → RR | Manual sync ("Sync from Square" button in Product Management) | Product Data Mapping |
| Staff (Team Member) | Manual link | Enter the Team Member ID when creating staff on the RR side | Staff Data Mapping |
Importing the product master (optional)
Transaction data begins syncing automatically as soon as the POS connection is complete, but importing the product master (the list of product names, SKUs, categories, prices, etc.) is optional and up to the store operator. Import it if you want to enter cost prices on the ReceiptRoller side for profit analysis, or if you want to manage additional product attributes (brand, supplier, JAN code, etc.).
- Open "Product Management" on the store admin screen.
- Click "Sync from Square" from the menu (⋮ icon) in the upper right.
- All products and categories are imported via the Square Catalog API, and new additions/updates are applied automatically.
- Once the sync completes, the number of imported items is shown at the top of the screen.
For details on which fields are imported, field-level support, and Square-specific behavior (such as handling of multiple variations and why cost price might not be imported), see Mapping Between Square Product Data and ReceiptRoller Product Data.
Even without importing the product master, per-product sales analysis still works (product names and categories are aggregated automatically from transaction line items). Only import it if you need cost management or profit analysis.
Manually syncing data
Click the terminal card to open the detail screen, then click the "Sync with Square" button. You can manually import transaction data from the past 30 days (or since the last sync). After the sync completes, "Synced with Square. Retrieved ○ transactions." is displayed.
Since data is normally sent in real time at each checkout, manual sync is typically used only for the initial connection or when a re-sync is needed.
Editing or removing a terminal
You can edit the terminal name or location information from the terminal detail screen. To disconnect, remove the terminal using the "Delete" button.
Checking the internal data structure
For details on how transaction data retrieved from Square maps to ReceiptRoller's internal transaction data model, see the technical reference articles. They cover field-by-field mapping tables, status conversion, line-item and customer matching, and automatic OAuth token refresh.
- Mapping Between Square Transaction Data and ReceiptRoller Transaction Data — technical details
- Mapping Between Square Customer Data and ReceiptRoller Customer Data
- Mapping Between Square Product Data and ReceiptRoller Product Data
- PosTransactionDto Reference (Field Reference) — all fields of the transaction data model
Related articles
-
Staff Sync via Square IntegrationExplains how stores connected to Square POS can sync Team Member information bidirectionally with ReceiptRoller — job assignments, pay rates, assigned stores, owner permissions, and more, kept aligned with Square.
-
Two-Way Member Information Sync with Smaregi/SquareLearn how ReceiptRoller's member information syncs bidirectionally with connected POS systems like Smaregi and Square. Covers which fields sync, sync timing, conflict priority rules, new customer matching, supported POS systems, and troubleshooting.
-
Square Customer Data and Receipt Roller Customer Data MappingExplains how customers registered in Square Customer Directory are converted into Receipt Roller's customer data (CrmCustomerDto), field by field. Covers the given_name / family_name correspondence, address decomposition logic, and how reference_id is handled.
-
Connecting with POSAn overview of the POS systems that can connect with ReceiptRoller and how to connect them. Supports Square and Smaregi.
-
Square Staff Data and Receipt Roller Staff Data MappingExplains how Square Team Members are linked to Receipt Roller's staff data (StaffDto). Covers how to use manual linking, the logic for resolving who is attributed to a transaction, and the key fields in the Team Member API.