Keystone Documentation

Appearance

Customer Data Overview ​

Introduction ​

Customer data is automatically synced between your Shopify store and the Keystone Loyalty Rewards app. This ensures that customer information, loyalty points, and activity remain up-to-date across both platforms.

How Customer Data Syncing Works ​

Initial Sync on Install ​

When you install the app, an automatic sync process begins:

  1. Job Dispatched: A background job is queued to sync all existing Shopify customers
  2. Customer Import: Each Shopify customer is imported into the app
  3. Data Storage: Customer information and protected data are stored securely

Timeline:

  • Small stores (< 1,000 customers): Minutes
  • Medium stores (1,000-10,000 customers): Hours
  • Large stores (> 10,000 customers): May take several hours

First Sync

The initial customer sync runs automatically in the background. You can continue setting up your loyalty program while this completes.

Ongoing Customer Sync ​

After the initial sync, customer data stays synchronized automatically through webhooks:

Customer Account Created ​

When a customer creates an account in your Shopify store:

  1. App receives customers/create webhook
  2. Customer record created in the app
  3. Initial points balance set to 0
  4. Customer becomes eligible for earning rules (e.g., signup points)

Customer Information Updated ​

When a customer updates their account information:

  1. App receives customers/update webhook
  2. Customer record updated in the app
  3. If customer doesn't exist (edge case), they're created
  4. Protected customer data refreshed

Updated Information:

  • Name
  • Email address
  • Customer tags
  • Account status

Customer Account Deleted ​

When a customer account is deleted in Shopify:

  1. App receives customers/delete webhook
  2. Customer data is soft-deleted (marked as deleted but retained temporarily)
  3. After retention period, customer data is permanently deleted
  4. Points balance and transaction history are removed

Retention Period: Customer data is retained for 90 days after deletion for compliance and recovery purposes.

Customer Merging ​

When two customer accounts are merged in Shopify:

  1. App receives customers/merge webhook
  2. Source customer (merged from) is deleted
  3. Target customer (merged into) receives combined data:
    • Points Balance: Combined from both accounts
    • Points Earned: Combined totals
    • Transactions: Moved to target customer (duplicates removed)
  4. One-time transactions (e.g., signup) are not duplicated

Customer Statistics ​

Each customer has associated statistics automatically calculated from their transactions:

StatisticDescription
Points EarnedTotal points earned from all earning rules
Points ClaimedTotal points spent on rewards
Points RedeemedTotal points redeemed (from used discount codes/gift cards)
Points BalanceCurrent available points (Earned - Claimed)
Spent to Earn PointsTotal order value that generated points
Spent to Redeem PointsTotal order value when redeeming rewards

Statistics Update:

  • Real-time as transactions occur
  • Calculated from transaction history

Manual Customer Sync ​

Merchants can manually trigger a customer sync if needed.

When to Use:

  • After bulk customer imports in Shopify
  • If customer data appears out of sync
  • After resolving sync issues

How to Sync:

  1. Navigate to Customers data page
  2. Click Sync Customers button
  3. Background job starts syncing

Rate Limit: 1 sync per merchant per 24 hours

Sync Limitations

Manual sync is rate-limited to once per 24 hours per store to prevent system overload. The sync runs in the background and may take time for large customer bases.

Summary ​

Customer data syncing happens automatically through Shopify webhooks, keeping customer information, points balances, and transaction history synchronized between your store and the loyalty app. The initial sync imports all existing customers when you install the app, and ongoing syncs handle customer creation, updates, deletion, and merging in real-time.