Introduction

Use the Points Logs CSV importer when you want to backfill historical loyalty activity into Rivo. This creates transaction history rows (not just a one-time balance adjustment), then recalculates each affected customer’s points or credits balance from that imported history.

This is useful for migrations, historical corrections, and bringing older activity into your current program records.

In migration projects, a backfill means importing older transaction history so customers’ past earning and spending activity appears in Rivo (with historical dates, if provided), instead of starting everyone from today.

Before You Import

Go to Settings > CSV Imports.
Set Data Type to Points Logs.
Click Download Template.
Prepare your CSV using the required format below.

CSV Format

Your file must include:

A customer identifier column: customer_id or email
A transaction amount column: points_amount or credits_amount

Optional columns:

source
points_amount
credits_amount
internal_note
external_note
applied_at
approved_at
revoked_at
expires_at
order_id
custom_action_name
earning_rule_id
points_purchases_id

Header aliases accepted

The importer accepts common header variants, including:

customer_id, Customer ID, CustomerID, Shopify Customer ID
email, Email, customer_email, Customer Email, Shopify Customer Email
points_amount, Points Amount
credits_amount, Credits Amount
source, Source
internal_note, Internal Note
external_note, External Note
applied_at, Applied At
approved_at, Approved At
revoked_at, Revoked At
expires_at, Expires At
order_id, Order ID, points_order_id
custom_action_name, Custom Action Name
earning_rule_id, Earning Rule ID
points_purchases_id, Points Purchases ID

Headers must match one of the accepted names above. Rivo trims extra spaces around a header, but it does not treat every casing as the same header. For example, Customer ID is accepted, but CUSTOMER ID is not.

If a required customer or amount header is not recognized, the upload may show a missing columns error. If another header is not recognized, Rivo ignores that column during processing. This can cause rows to be skipped if Rivo cannot read a customer identifier or a non-zero points or credits amount, even when the import later shows Completed.

Best practice: start from the downloaded template and keep the header names unchanged.

Amount behavior

Positive values add points or credits.
Negative values deduct points or credits.
Rows where both amounts are zero are skipped.
A row can include both points_amount and credits_amount.

Date behavior

If applied_at is missing or invalid, Rivo uses the current timestamp.
If approved_at is missing or invalid, it defaults to the final applied_at value.
Invalid revoked_at or expires_at values are ignored.

Matching and Processing Rules

Use one matching method consistently

Do not mix lookup methods in one CSV.

During processing, if a group of rows includes customer_id, that group uses customer ID matching.
In those groups, rows without a valid customer_id can be skipped even if they include an email.

Best practice: use either customer IDs for all rows, or emails for all rows, so matching behavior stays predictable.

Existing customers only

Rows are imported only when the customer already exists in your store’s Rivo customer records.
Unknown customers are skipped.

Duplicate protection

If you import the same transaction row again (including across separate import runs), duplicate rows are ignored.

To count as the same row, the core transaction details must match, including the customer, source, amounts, notes, selected action or rule details, and applied timestamp. If you change an imported file between attempts, Rivo may treat changed rows as new transactions.

Upload and Monitor Progress

In Settings > CSV Imports , upload your file in the dropzone.
Rivo queues processing in the background.
Open CSV Import Progress and click View CSV Imports to monitor status.

Possible statuses include Pending , Processing , Completed , Failed , Reverting , Reverted , and Cancelled.

For large files, processing time scales with row count. Typical timing guidance:

Up to 100 rows: a few seconds
101 to 1,000 rows: a few minutes
1,001 to 10,000 rows: up to 20 minutes
10,001 to 100,000 rows: up to an hour
Over 100,000 rows: a few hours

If an import sits in Pending , it is waiting in the background queue before processing starts.

What Happens After Import

After rows are imported:

Transaction history entries are created for matched customers.
Customer balances are recalculated for the affected balance type (points and/or credits).
Imported rows are tagged for traceability so they can be reverted later from CSV Imports history.
Imported positive rows can appear as earned activity in loyalty analytics and the Outstanding Earnings report. Imported negative rows can appear as spent activity. Reporting settings may affect whether imported adjustments are included.
Imported credits are recorded according to your store’s current credit setup.

Customer-facing message records are not generated by this importer.

How imports affect the Outstanding Earnings report

Historical imports are treated as real balance activity for reporting. If you import past balances during a migration, the imported positive amounts can increase the Earned column in the Outstanding Earnings report for the dates on the imported rows. If you leave the date columns blank, the activity is reported on the import date.

This is expected and does not mean customers earned those balances again in Rivo. It means the report now includes the historical balance activity you imported so that customer balances and liability reporting can be rebuilt from transaction history.

If the post-migration report looks unexpectedly negative, switch the report to Cumulative Balance and check whether the selected date range includes imported deductions without the matching earlier positive balance activity.

What customers and admins will see

In admin, imported transactions appear in customer points/credits history and in the CSV Imports history.
In customer-facing activity history, the customer-facing note uses external_note when you provide one.
internal_note is for internal reference and traceability.
Some stores have per-entry visibility controls enabled for points logs. If available in your account, you can hide specific entries from customer view after import.

Revert an Imported File

If you need to roll back a completed import:

Go to Settings > CSV Imports.
Click View CSV Imports.
Find the completed import and click Revert.

This queues a rollback for that import and moves it through Reverting to Reverted status.

The Revert button appears for supported completed imports. If you don’t see it for an older import, contact support for help.

Common Questions About Actions and Expiry

Can I tie uploaded transactions to a specific earning action?

Yes. In a Points Logs import, you can map transactions to specific activity using the source column, and optionally add custom_action_name and earning_rule_id when needed.

Imported historical rows are added as transaction history. They are not rechecked against that activity’s usual earning limits.

If you only need to change balances (not record a specific action history), use manual balance adjustments instead.

Can monthly uploads use different point or credit amounts per customer?

Yes. Every row can use a different value, including positive and negative amounts.

This works well for partner reports, offline campaigns, and one-off corrections where each customer’s amount is different.

How does expiry work for uploaded transactions vs manual adjustments?

For Points Logs imports , use expires_at if you want a specific expiry date on each imported row.
If expires_at is blank in a Points Logs import, Rivo does not add an expiry date for that imported row.
For manual balance adjustments (single-customer or bulk balance updates), expiry follows your points or credits expiry settings.
For earning-rule activity (like order, birthday, or other configured ways to earn), expiry follows your earning setup and program expiry configuration.

FAQ

Can I import points and credits in one file?
Yes. A row can contain both points_amount and credits_amount.

Will this create new customers from email addresses in my CSV?
No. Only customers that already exist in your Rivo customer records are updated.

What if my source value is blank or not recognized?
Rivo assigns a default import source automatically.

Can I safely retry an import file?
Yes, if you retry the same unchanged file.
To avoid accidental duplicates or unexpected skipped rows, do not edit rows between attempts.

Can I upload historical timestamps?
Yes. Use applied_at and approved_at in your CSV when you want historical dates preserved.

Import Historical Points or Credits Transactions