Customers registered in Square Customer Directory are automatically converted into Receipt Roller's customer data (CrmCustomerDto) after connecting Square to Receipt Roller. This article summarizes the field-by-field correspondence and the quirks specific to Square.

For the two-way sync mechanism for membership data itself (timing, priority in case of conflicts, troubleshooting), see Two-way membership data sync with Smaregi / Square. This article is strictly a technical document focused on "which field maps to what."

Field mapping table

Fields that are not imported

• Name reading / kana (LastNameKana / FirstNameKana) — blank because Square has no kana field.
• Gender (Gender) — not a standard field in Square Customer Directory.
• Square-side groups (group_ids) — Square's group feature operates at a different granularity than Receipt Roller's MembershipLevel or Tags, so it is not imported in the current version.
• Square-side segments (segment_ids) — these are dynamically computed segments, so carrying them over to the Receipt Roller side has little meaning and is not supported.

Matching and new registrations

When new customer information arrives from Square, Receipt Roller performs duplicate-person matching against existing customers in the following order.

1. MembershipCode (exact match with Square's reference_id)
2. Email (exact match after lowercasing and trimming leading/trailing whitespace)
3. Phone (exact match after E.164 normalization)

If none of these match, the customer is added to the CRM as new. If a match is found, the existing customer's information is updated (field-level last-write-wins).

Sync timing

• Registering/updating members (Square → Receipt Roller): Reflected in the CRM within seconds via Square Webhooks (customer.created / customer.updated).
• Periodic backup: As a fallback in case the webhook doesn't arrive, differences are fetched via the SearchCustomers API every hour.
• Receipt Roller → Square: The moment a customer registers as a member or updates their information in the app, a call to Square's CreateCustomer / UpdateCustomer is added to the queue. Usually reflected within seconds to a few minutes.

Points to note

• If a customer is physically deleted on the Square side, matching on the Receipt Roller side stops working. Please be careful when deleting from the Square dashboard.
• If staff manually rewrite Square's reference_id, the MembershipCode match on the Receipt Roller side breaks. We recommend not changing this field once it is treated as a membership number.
• Square's address is a structured field, but in many cases store staff enter everything into address_line_1 without distinguishing "house number" from "building name" in the UI. In that case, Address2 will be blank.
• Contact the development team if you'd like to make use of Square's groups or segments as Receipt Roller tags.

Related guides

• CrmCustomerDto reference (for developers) — full field specification of the canonical model
• Two-way membership data sync with Smaregi / Square
• Square transaction data and Receipt Roller transaction data mapping
• Square POS integration setup