Skip to main content
CSV import lets you bring customer and payment data into Refairn by uploading a spreadsheet—no API calls, no webhook configuration, no code. You prepare a file with your customer records, map each one to an agent using the agent’s referral code, and upload it. Refairn creates the corresponding lead and commission records automatically.
CSV import is the right starting point when you are validating your partner channel. Before investing engineering time in an API integration, run your first cohort of agents manually: upload paying customers, confirm that commissions calculate correctly, and verify that partner-sourced customers are retaining as expected. Once you have proof the channel works, automate with the API or payment provider webhooks.

​
When to use CSV import

Use CSV import when:
  • You are onboarding your first batch of agents and want to test the program before building a technical integration.
  • Your SaaS does not yet have a development resource available to instrument the API.
  • You need to backfill historical customers who converted before your integration was live.
  • You are running a time-limited beta and do not want to build automation for a short-lived test.
Do not use CSV import as a permanent solution in a live program. Because it requires manual effort and is only as current as your last upload, real-time commission visibility for agents is not possible. Once your program is active and agents are actively referring customers, switch to the API integration or payment provider webhooks.

​
CSV format

Your file must be a plain .csv (comma-separated values) file with a header row matching the column names below. Column order does not matter—Refairn matches by header name, not position. 
Customer Name,Customer Email,Plan,Amount Paid,Subscription Status,Agent Code,Payment Date,Renewal Date
Jane Smith,jane@example.com,Pro,99,active,AGENT123,2026-06-14,2026-07-14
Marcus Osei,marcus@example.com,Starter,29,active,AGENT456,2026-06-10,2026-07-10
Priya Kapoor,priya@example.com,Pro,99,cancelled,AGENT123,2026-05-01,

​
Column reference

ColumnRequiredFormatDescription
Customer NameYesTextThe customer’s full name
Customer EmailYesValid email addressUsed as the primary key for deduplication and attribution matching
PlanYesTextThe name of the subscription plan the customer is on
Amount PaidYesNumber (no currency symbol)The payment amount in your base currency. Example: 99 not $99.00
Subscription StatusYesactive, cancelled, past_due, trialingThe current state of the subscription
Agent CodeYesTextThe referral code of the agent who referred this customer. Must match an active agent in your program
Payment DateYesYYYY-MM-DDThe date the payment was confirmed
Renewal DateNoYYYY-MM-DDThe next expected renewal date. Leave blank for one-time payments or cancelled subscriptions

​
Preparing your file

1

Export your customer data

Pull a list of paying customers from your billing system, CRM, or database. You need at minimum: name, email, plan, payment amount, and payment date.
2

Add agent codes

For each customer, identify which agent referred them and add that agent’s referral code in the Agent Code column. You can find each agent’s code in Agents → [Agent Name] → Profile in your Refairn dashboard. If a customer was not referred by an agent, leave the Agent Code column blank—the row will be imported as an unattributed customer.
3

Format dates

Ensure all dates in Payment Date and Renewal Date are in YYYY-MM-DD format. For example, June 14, 2026 should be 2026-06-14. Dates in other formats (MM/DD/YYYY, DD-MM-YYYY, etc.) will fail validation.
4

Format amounts

Remove currency symbols and thousand-separator commas from the Amount Paid column. Use plain numbers: 99 or 1299.50, not $99 or 1,299.50.
5

Check subscription status values

The Subscription Status column accepts only: active, cancelled, past_due, or trialing. Correct any other values before uploading.
6

Save as CSV

Save or export your file as a .csv file encoded in UTF-8. Most spreadsheet applications (Excel, Google Sheets, LibreOffice Calc) have a “Save as CSV” or “Download as .csv” option.

​
Uploading your file

1

Navigate to the import screen

In your Refairn business dashboard, go to Customers → Import or Settings → Import. Click Upload CSV.
2

Select your file

Click Choose file and select the .csv file you prepared. Refairn will preview the first five rows and highlight any column mapping issues.
3

Review the preview

Check that Refairn has mapped each column correctly. If any column headers are unrecognized, a warning will appear—correct the header names in your file and re-upload.
4

Confirm and import

Click Import. Refairn processes the file row by row. A progress indicator shows how many rows have been processed. When complete, a summary shows how many customers were created, updated, or skipped due to errors.

​
What happens after upload

For each valid row in your file, Refairn:
  1. Creates or updates a customer record using the Customer Email as the unique key. If the email already exists in your program, the existing record is updated rather than duplicated.
  2. Assigns agent attribution based on the Agent Code column. If the code matches an active agent in your program, the customer is linked to that agent.
  3. Creates a commission record using the Amount Paid and your program’s commission rules. The commission is created in pending status and moves to approved after the configured hold period passes.
  4. Sets subscription state from the Subscription Status column. Cancelled subscriptions do not generate recurring commissions for future renewals.
Agents can see their attributed customers and pending commissions in their agent dashboard immediately after the import completes.

​
Validation errors

If any rows in your file contain errors, Refairn will flag them and skip those rows. The import still processes all valid rows. After the import, download the error report to see exactly which rows failed and why.
ErrorCauseFix
Invalid emailMalformed or missing email addressCorrect the email format in the row
Unknown agent codeThe Agent Code does not match any active agentVerify the code in Agents → Profile or leave blank
Invalid date formatDate is not in YYYY-MM-DD formatReformat the date column
Invalid amountAmount contains non-numeric charactersRemove currency symbols and commas
Invalid statusSubscription Status is not a recognised valueUse one of: active, cancelled, past_due, trialing
Duplicate email on same dateA record with the same email and payment date already existsRemove the duplicate row or update the existing record manually
After fixing errors in your file, re-upload only the rows that failed—rows already imported successfully will be deduplicated by email and payment date and will not create duplicate records.

​
Limitations

CSV import is intentionally simple, and that simplicity comes with trade-offs:
  • Not real-time. Agent dashboards only reflect data as of your last upload. If you import weekly, agents see a week-old view of their commissions.
  • Manual effort. Someone on your team must export data, prepare the file, and upload it on a regular cadence.
  • No event history. CSV import creates snapshot records. Refairn does not receive lifecycle events (upgrades, downgrades, cancellations) between imports unless you include them in each new file.
  • Attribution must be known. You must identify the correct agent for each customer yourself. With API integration, attribution is captured automatically at the moment the referral link is clicked.

​
When to graduate to API or webhooks

Move away from CSV import when:
  • You have confirmed that partner-referred customers convert and retain well enough to justify automation investment.
  • You have more than a handful of active agents and manual attribution is becoming error-prone.
  • Agents need real-time visibility into their commission pipeline to stay motivated.
  • You want Refairn to capture customer lifecycle events (upgrades, cancellations, reactivations) automatically.
See API Integration and Payment Providers to set up automated event tracking.