The Points History import brings your customers' past points activity into Mage, so their account looks complete from the day you launch. Every entry you import appears in the customer's points history, right alongside the points they earn going forward.
You map each entry to one of your earning rules, upload a single CSV file, and Mage imports the activity while you watch the progress live.
This import adds activity to your customers' points history. It does not change their points balances. Balances are set when you import your loyalty members.
Before You Start
Import your loyalty members first. This import only adds activity to customers who are already in Mage. Run the Loyalty Members import before this one. Any entry for a customer Mage cannot find is skipped, and the results page lists them.
Set up your earning rules. Each entry is linked to one of your earning rules, such as Purchase or Sign up. Create the earning rules you want to map to before you import.
How Mapping Works
Every row in your file is linked to one of your Mage earning rules using that rule's ID. This is how Mage knows what each entry was, for example a purchase or a sign up.
To find your IDs, open the importer and choose Points Logs. A card titled Your earning rules lists every rule with a Copy button next to its ID. Copy the ID for each rule and paste it into the earning_rule_id column for the matching rows.
Preparing Your File
Download the template from the import page for a ready-made example. Your file needs one row per points entry, with these columns:
Column | Required | What it does |
Required* | The customer's email address, used to find them in your store. | |
customer_id | Required* | The customer's Shopify ID. Use this instead of email if your export includes it. |
points_amount | Required | The number of points earned, for example 250. |
earning_rule_id | Required | The ID of the earning rule this entry belongs to. |
source | Optional | A label from your previous platform, kept for your own reference. |
internal_note | Optional | A private note for your team. |
applied_at | Optional | The original date of the activity, so history appears in the right order. |
order_id | Optional | The Shopify order this relates to, if any. |
order_number | Optional | The order number to display, for example #1001. |
expires_at | Optional | Kept for your reference only. |
*Provide either email or customer_id for each row.
Leave any optional cell empty and Mage skips that detail. For applied_at you can use a simple date like 2024-01-15, or keep the full date and time from your previous platform. Files can contain up to 500,000 rows.
What Gets Imported, and What Gets Skipped
Mage imports the points your customers earned, and quietly skips the rest. You do not need to clean your file beforehand.
Imported: entries with a positive points value that are mapped to an earning rule.
Skipped automatically: negative entries such as cancellations, expired points, and redeemed points. You do not need to remove these. Mage skips them and tells you how many.
Skipped: rows with no earning_rule_id. You do not have to map every row. Anything you leave unmapped is skipped.
Flagged to fix: rows with an earning_rule_id that does not match one of your rules. These show on the results page so you can correct the ID and upload again.
Skipped: entries for customers Mage cannot find. Import your loyalty members first so they exist in Mage.
Running the Import
Open the importer. In Mage, go to Settings, then CSV Import.
Choose Points Logs as the import type.
Copy your earning rule IDs from the Your earning rules card and add them to the earning_rule_id column in your file.
Upload your CSV. Mage checks every row first and shows a preview, including how many rows will import and how many will be skipped. If anything needs fixing, you will see exactly which rows and why.
Click Import. You are taken to a progress page that updates live. You can safely close it; the import keeps running in the background and you can come back any time.
Important: Refunds on Past Orders
The points you import are a record of past activity. If a customer later returns or refunds an order that was placed before you moved to Mage, those imported points are not automatically removed.
This only affects orders from before your migration. Orders placed after you move to Mage work as normal, and refunds adjust points automatically. If you ever need to correct a specific customer, you can adjust their points by hand from their customer page in Mage.
Before You Upload Again
Each upload adds new entries. Uploading the same points file twice will create duplicate history. Mage shows a warning if you have imported points history before.
If you need to re-do an import, message us on live chat first. We can remove the previous entries so you can start fresh without duplicates.
Migrating From Smile
Moving from Smile.io? Export your points activity from Smile, open the file in a spreadsheet, and rename these column headers:
Smile column | Rename to |
Points change | points_amount |
Date | applied_at |
Then add one new column called earning_rule_id. Look at Smile's Comment column to see what each activity was, and paste in the ID of the matching Mage earning rule.
For example:
Placed an order uses your Purchase rule ID
Signed up uses your Sign up rule ID
Wrote a product review uses your Review rule ID
Followed on Instagram uses your social follow rule ID
If you would like to keep Smile's original wording next to each entry, rename Comment to source as well.
A few things to know about Smile exports:
You do not need to clean out negative rows. Entries like Canceled: Placed an order, Points expired after a period of inactivity, and Points spent on a reward are skipped automatically.
Only map the activity you want to keep. Leave earning_rule_id empty for anything else and it is skipped.
Other Smile columns, such as Smile Customer ID, New points balance, Type, First name, and Last name, can stay in the file. Mage ignores them.
The renamed headers must be lowercase with underscores, exactly as shown.
Questions about your migration? Message us on live chat and we will walk you through it.