Imports

Overview

The Imports feature allows merchants to bulk update customer point balances or make point adjustments using file uploads. This is useful for migrating from other systems, correcting balances, or running promotional campaigns that require bulk point changes.

Accessing Imports

1. Open Keystone Loyalty Rewards app
2. Navigate to Customer Data > Imports

Import Types

Import Balance

Set customer point balances to specific values using a file upload.

How It Works:

• Upload file with customer identifiers and target balances
• System identifies customers by Shopify ID or email
• Customer balances are set to the specified values
• Creates "Import" transaction for each customer

Use Cases:

• Migrating from another loyalty platform
• Setting initial balances for existing customers
• Correcting balances after system issues
• Promotional balance resets

Example:

Customer (email): sarah@example.com
Current Balance: 500 points
Import Balance: 2,000 points
Result: Balance set to 2,000 points
Transaction: Import (+1,500 points)

Import Adjustments

Make point adjustments (add or remove points) using a file upload.

How It Works:

• Upload file with customer identifiers and adjustment amounts
• System identifies customers by Shopify ID or email
• Adjustments applied to current balances (+ or -)
• Creates "Adjustment" transaction for each customer

Use Cases:

• Bulk promotional bonuses
• Correcting calculation errors across multiple customers
• Seasonal campaign rewards
• Compensation for service issues

Example:

Customer (email): sarah@example.com
Current Balance: 500 points
Import Adjustment: +300 points
Result: New balance 800 points
Transaction: Adjustment (+300 points)

Supported File Formats

The import feature supports multiple file formats:

Format	Extension	Description
CSV	.csv	Comma-separated values
Excel	.xlsx	Microsoft Excel format
TSV	.tsv	Tab-separated values

File Structure

Import Balance File

Required Columns:

Column	Description	Format
Customer Identifier	Shopify customer ID OR email address	12345678 or customer@example.com
Balance	Target point balance	Positive number (e.g., 1000)

Optional Columns:

• Reason (for transaction record)

Import Adjustments File

Required Columns:

Column	Description	Format
Customer Identifier	Shopify customer ID OR email address	12345678 or customer@example.com
Adjustment	Points to add (positive) or remove (negative)	Number with sign (e.g., +500 or -200)

Optional Columns:

• Reason (for transaction record)

Import Process

Step 1: Download Sample File

1. Navigate to Customer Data > Imports
2. Select import type (Balance or Adjustments)
3. Click Download Sample File
4. Choose file format (CSV, XLSX, or TSV)
5. Sample file downloads with correct structure

Sample File Contents:

• Pre-formatted columns
• Example rows for reference
• Instructions in header comments (CSV only)

Step 2: Prepare Your File

1. Open the sample file
2. Remove example rows
3. Add your customer data:
   • Customer Identifier: Use Shopify customer ID OR email
   • Balance/Adjustment: Enter appropriate values
   • Reason (optional): Add context for transactions
4. Save the file

Best Practices:

• Use Shopify customer ID when possible (more reliable than email)
• Include reasons for better tracking
• Verify data before uploading
• Test with small file first

Step 3: Upload File

1. Click Upload File button
2. Select your prepared file
3. Confirm file format is correct
4. Click Start Import

Step 4: Processing

Background Job:

• Import queued for processing
• Job runs in background
• Can continue working during import

Processing Steps:

1. Validate customer identifiers
2. Match customers in database
3. Apply balance changes or adjustments
4. Create transaction records
5. Generate completion report

Step 5: Completion Report

Report Includes:

• Total rows processed
• Successful imports
• Failed imports (with reasons)
• Summary of point changes

Download Report:

• Available immediately after completion
• CSV format
• Shows success/failure per customer
• Includes error messages for failures

Customer Identification

Shopify Customer ID

Format: Numeric ID (e.g., 12345678901)

Advantages:

• Most reliable identifier
• Unique per customer
• Never changes

How to Find:

• Export customers from Shopify
• View in customer URL in Shopify admin
• Include in customer exports from app

Email Address

Format: Valid email (e.g., customer@example.com)

Advantages:

• More recognizable
• Easier to work with manually

Limitations:

• Customers can change email
• Must match exactly (case-sensitive)

Example:

customer_identifier,balance
sarah@example.com,2000
john@example.com,1500

Customer Matching

If a customer identifier doesn't match any customer in your store, that row will be skipped and reported in the completion report.

Validation and Errors

File Validation

Common Errors:

Error	Cause	Solution
Invalid file format	Unsupported format or corrupted file	Use CSV, XLSX, or TSV only
Missing columns	Required columns not found	Use sample file as template
Empty file	File has no data rows	Add customer data
Duplicate identifiers	Same customer multiple times	Remove duplicates

Customer Validation

Common Errors:

Error	Cause	Solution
Customer not found	ID/email doesn't exist	Verify customer exists in store
Invalid identifier	Wrong format	Check Shopify ID is numeric or email is valid
Multiple matches	Email matches multiple customers	Use Shopify ID instead

Value Validation

Balance Import Errors:

Error	Cause	Solution
Negative balance	Balance value is negative	Use positive numbers only
Invalid number	Non-numeric value	Ensure balance is a number
Balance too large	Exceeds maximum	Check point value is reasonable

Adjustment Import Errors:

Error	Cause	Solution
Would create negative balance	Adjustment would go below 0	Reduce adjustment amount
Invalid number	Non-numeric value	Ensure adjustment is a number
Missing sign	No + or - indicator	Add + for additions, - for subtractions

Rate Limiting

To prevent system overload, imports are rate-limited:

Limits:

• 1 import per 5 minutes per merchant
• Cannot start new import while one is queued or running

If You Try to Import Too Soon:

• Error message displayed
• Shows time remaining until next import allowed
• Shows status of current import (if running)

Example Message:

Import rate limit reached.
Please wait 3 minutes before starting another import.

Current import status: Processing (45% complete)

Rate Limiting

Plan your imports accordingly. For very large files, consider splitting into multiple smaller files and importing over time.

Transaction Records

All successful imports create transaction records:

Import Balance Transactions:

• Type: "Import"
• Points change: Difference between old and new balance
• Message: Reason (if provided) or "Balance imported"
• Date: Import processing date

Import Adjustment Transactions:

• Type: "Adjustment"
• Points change: Adjustment amount (+ or -)
• Message: Reason (if provided) or "Bulk adjustment imported"
• Date: Import processing date

Viewing Transactions:

• Customer transaction history
• Store-wide transaction log
• Transaction exports

Use Cases

Migration from Another Platform

Scenario: Moving from previous loyalty system

Process:

1. Export customer balances from old system
2. Match customers by email or ID
3. Format as Import Balance file
4. Upload to set initial balances

Example:

customer_identifier,balance,reason
sarah@example.com,2500,Migrated from PreviousLoyalty
john@example.com,1800,Migrated from PreviousLoyalty

Promotional Campaign

Scenario: Give 500 bonus points to high-tier customers

Process:

1. Export high-tier customers from app
2. Create Import Adjustments file
3. Set adjustment to +500 for all
4. Upload to apply bonuses

Example:

customer_identifier,adjustment,reason
12345678,+500,Gold tier appreciation bonus - June 2024
98765432,+500,Gold tier appreciation bonus - June 2024

Error Correction

Scenario: Remove duplicate points from affected customers

Process:

1. Identify affected customers
2. Calculate points to remove
3. Create Import Adjustments file with negative values
4. Upload to correct balances

Example:

customer_identifier,adjustment,reason
customer@example.com,-200,Correction for duplicate order points
john@example.com,-350,Correction for duplicate order points

Initial Setup

Scenario: Setting up loyalty program with existing customers

Process:

1. Export all customers
2. Define starting balance policy
3. Create Import Balance file
4. Upload to set all balances

Example:

customer_identifier,balance,reason
customer1@example.com,100,Welcome to loyalty program
customer2@example.com,100,Welcome to loyalty program

Best Practices

File Preparation

Do:

• Use sample file as template
• Test with small file first
• Include reasons for audit trail
• Verify customer identifiers
• Remove duplicate rows
• Use Shopify ID when possible

Don't:

• Modify column headers
• Leave empty required columns
• Include customers not in your store
• Use outdated customer emails
• Import same file twice

Data Verification

Before Import:

• Double-check point values
• Verify customer identifiers are correct
• Ensure adjustments won't create negative balances
• Review total points being distributed

After Import:

• Review completion report
• Check transaction log
• Verify customer balances updated
• Investigate any failures

Large Imports

For Files with 1,000+ Customers:

• Allow extra processing time
• Monitor completion report
• Consider splitting into smaller files
• Schedule during off-peak hours
• Export current balances first (backup)

Related Pages

• Customer Data Overview - How customer data works
• Managing Customers - Browse customers
• Adjustments - Manual adjustments
• Transactions - View transaction history
• Exports - Export customer data

Summary

The Imports feature enables bulk updates to customer point balances through file uploads. Use Import Balance to set specific balance values or Import Adjustments to add/remove points. Supported file formats include CSV, XLSX, and TSV. The import process validates customer identifiers, applies changes, creates transaction records, and provides a detailed completion report. Rate limiting prevents system overload by allowing one import per 5 minutes. All imports create audit-friendly transaction records with optional reasons for full transparency.