Quick start
- Export your transactions from your CRM, store or spreadsheet: one row per gift, order or payment, with a transaction ID, a donor or customer ID, the date, the amount and the type. Names, emails and addresses can stay in the file — we remove them as we read it.
- Go to Uploads › Upload new file (or choose Upload transactions on a matrix). Under What's in this file?, keep Gifts or Purchases selected.
- Drag your CSV, Excel or ZIP file onto the page, or choose Choose file. Keep the page open until the progress bar finishes and you land on the upload's own page.
- In Review your columns, check what each column is Used as. Most files match on their own.
- In Match your transaction types, give every value a type.
- Choose Import transactions (or Import and score when you came from a matrix). When it says Imported, build a matrix from it.
What to upload and why
A transactions file is your history: every gift or purchase, payment and refund, one row each. Every matrix and True segments is scored from it, and you can build as many as you like from the same upload. You can also connect a CRM instead of uploading.
Tip: Export everything you have rather than a single year. Matrices count the last 3 years by default, named segments show movement once your file reaches back more than a year, and True segments work best with three or more years.
Transactions or engagement: what's in this file?
The upload page asks What's in this file? before you choose a file:
- Gifts or Purchases (transactions)
- One row per gift, order or payment. This is what every matrix is built from, and what most of this page is about.
- Engagement
- Activities such as events attended, volunteer shifts, logins or email opens, used by RFE matrices. See Engagement files.
The column guide under the drop area changes with your choice. You can't change the choice once the file starts uploading — if you picked the wrong one, upload the file again. CRM connections only bring in transactions.
File types and size
| You can upload | Details |
|---|---|
| CSV and other text files | .csv, .txt or .tsv. Commas, tabs, semicolons or pipes between columns all work. The first row must hold the column names. |
| Excel workbooks | .xlsx, .xlsm, .xls or .xlsb. We read the first sheet that has data; you can pick another sheet in review. |
| ZIP files | A .zip holding exactly one CSV or Excel file. Folders and the hidden __MACOSX entries a Mac adds are ignored. |
Files can be up to 2 GB. The limit applies to the file you upload, so zipping a very large CSV is the easiest way to get under it. Empty files are refused before anything is sent.
The columns your file needs
A transactions file needs these five columns. Your headers don't have to use these exact names — see how we recognize your headers.
| Column | What it is | Example |
|---|---|---|
transactionid | A unique ID for each gift or payment — your CRM's gift or transaction ID. Two rows with the same ID are duplicates. | T-100231 |
constituentid or customerid | Your system's ID for the donor or customer. Never a name: an ID lets you look them up while TrueRFM never learns who they are. | C-004518 |
date | The date the gift was received. YYYY-MM-DD or MM/DD/YYYY are safest; other formats work too. | 2026-09-28 |
amount | The gift amount in dollars. Refunds as negative amounts. | 250.00 |
type | The kind of transaction. Your own labels are fine — you'll match each one to a type. | Recurring |
One more column is optional: capacity, a gift capacity rating in dollars from wealth screening (see below). Every other column either comes along as a detail or is left out — see Other columns.
How we recognize your headers
When we first read your file we compare each header with the names below, ignoring capital letters, spaces and punctuation — so Gift ID, gift_id and GIFT-ID are all the same. Columns are checked left to right, and each of the six roles goes to the first column that fits it. If your file has both Gift Date and Date, the first one becomes the date and the second is kept as a detail.
| Used as | Headers we recognize |
|---|---|
transactionid | Transaction ID, Trans ID, Gift ID, Gift System ID, Donation ID, Transaction Number, Gift Number, Receipt ID, Payment ID |
constituentid | Constituent ID, Const ID, Cons ID, Donor ID, Account ID, Contact ID, Supporter ID, Record ID, Constituent Number, Donor Number, Account Number, Lookup ID, Constituent Lookup ID, Customer ID, Cust ID, Customer Number, Client ID, Buyer ID, Member ID |
date | Date, Gift Date, Donation Date, Transaction Date, Received Date, Date Received, Payment Date, Close Date |
amount | Amount, Gift Amount, Donation Amount, Transaction Amount, Received Amount, Amount Received, Payment Amount, Total |
type | Type, Gift Type, Donation Type, Transaction Type, Gift Subtype, Gift Category, Category, Record Type, Order Type, Sale Type, Purchase Type |
capacity | Capacity, Capacity Rating, Gift Capacity, Wealth Rating, Estimated Capacity, Rating Capacity |
A header we don't recognize isn't a problem: the column comes in as Keep as detail, and you choose what it is in the review step.
Dates
We read these date formats:
| Format | Example (Sep 28, 2026) |
|---|---|
| YYYY-MM-DD | 2026-09-28 |
| YYYY/MM/DD | 2026/09/28 |
| MM/DD/YYYY | 09/28/2026 or 9/28/2026 |
| DD/MM/YYYY | 28/09/2026 |
| MM-DD-YYYY | 09-28-2026 |
| DD-MM-YYYY | 28-09-2026 |
| DD.MM.YYYY | 28.09.2026 |
| YYYYMMDD | 20260928 |
| MM/DD/YY | 09/28/26 |
A time after the date is ignored, so 2026-09-28T00:00:00 and 9/28/2026 12:00 AM both read as Sep 28, 2026. Dates stored as real dates in Excel are read directly, whatever they look like on screen.
We settle on one format for the whole file, so 03/04 means the same thing on every row. We look at the first 1,000 rows and pick the format that reads the most of them. When every date could be read either way — 03/04/2026 could be March 4 or April 3 — we choose month-first. You can see and change the choice in review: the column used as date has a Read as menu under its name.
Example: month-first or day-first?
A file's first dates are 03/04/2026, 05/06/2026 and 13/04/2026. Month-first reads two of them (there's no 13th month); day-first reads all three. We pick DD/MM/YYYY, and 03/04/2026 is read as April 3, 2026.
If the file only had the first two dates, both formats would read two, and we'd pick MM/DD/YYYY. If your dates are really day-first, change Read as to DD/MM/YYYY before you import.
A row whose date doesn't fit the chosen format is left out of the import with the reason “Date not readable”.
Amounts, refunds and negative numbers
Amounts can be written like $1,234.56, 1234.56, 250, -25 or (25.00) — parentheses mean negative, as in accounting. Use a period for cents; amounts like 1.234,56 aren't read. A row whose amount can't be read is left out with the reason “Amount not readable”.
A negative amount is a refund or an adjustment. Matrices subtract it from that person's amount, and it never counts as a transaction on its own. Give a refund row:
- its own transactionid — a refund that reuses the original gift's ID is a duplicate and is left out;
- the same constituentid as the gift it reverses;
- a type like the original gift's, such as one-time, so it's netted against money received.
Rows with a zero amount are imported but add nothing.
The optional capacity column
If you've had your donors wealth-screened, add a capacity column with each constituent's estimated gift capacity in dollars. It's read like an amount. For each constituent we keep the value on their latest gift (on the same date, the row further down the file wins); empty, zero or unreadable values are ignored. RFM scores don't use it today; it's kept so the column isn't lost, and isn't shown in View records.
Only one column can be used as capacity.
Other columns: kept as detail or ignored
Every other column whose name and values don't look like personal information comes in as Keep as detail. Funds, appeals, campaigns, payment methods and regions are typical. Kept details are stored with each gift (up to 400 characters per value) and are used in three places:
- View records — choose which detail columns show beside each constituent and gift. See Viewing records.
Don't need a column? Set it to Ignore in review and it isn't stored at all.
Careful: we remove columns whose names or values look personal, but a free-text column such as Notes, Comments or Acknowledgment text can still contain a name in among other words. Set columns like these to Ignore in review, or leave them out of your export.
A sample file
Here's a complete transactions file you could upload as it is. Copy it into a text editor and save it as gifts.csv, or open it in Excel.
transactionid,constituentid,date,amount,type,fund,appeal,capacity
T-100231,C-004518,2026-09-28,250.00,Recurring,General Operating,Monthly Giving,
T-100232,C-004519,2026-09-29,1000.00,One-time,Building Fund,Spring Appeal,250000
T-100233,C-004520,2026-10-01,50000.00,Pledge,Building Fund,Capital Campaign,
T-100234,C-004520,2026-10-15,10000.00,Pledge payment,Building Fund,Capital Campaign,
T-100235,C-004521,2026-10-20,100000.00,Planned,Endowment,,
T-100236,C-004522,2026-10-22,1500.00,In-kind,Gala,Gala 2026,
T-100237,C-004519,2026-10-23,-100.00,One-time,Building Fund,Spring Appeal,
What happens to it:
| Column | Used as |
|---|---|
transactionid, constituentid, date, amount, type | Matched by name to the five required columns. The dates are read as YYYY-MM-DD. |
capacity | Matched to capacity (optional). C-004519 gets a capacity of $250,000. |
fund, appeal | Keep as detail, to show and filter by in View records. |
All the type values (Recurring, One-time, Pledge, Pledge payment, Planned, In-kind) are matched for you. T-100237 is a $100 refund of part of C-004519's $1,000 gift: it has its own ID, so it's imported, and C-004519's money received comes to $900. All seven rows are imported.
How personal information is removed
You don't need to clean names and contact details out of your export. As we read the file the first time, we remove every column that looks like personal information — by its header, and by what's in it. A removed column's values are never stored, and it can't be switched back on.
Columns removed by their name
A column is removed when its header contains any of these (spaces, underscores, hyphens and periods count as spaces, and capitals don't matter):
- email or e-mail, phone, mobile, cell, fax;
- address, street, city, zip, postal, postcode;
- birth (birthdate, birthday), DOB, SSN, social security, tax ID;
- salutation, addressee, spouse, nickname, maiden, honoree, tribute name, in honor of, in memory of;
- a name: first name, last name, middle name, full name, given name, family name, surname, donor name, constituent name, contact name, account name, household name, org or organization name, company name, employer name, recognition name, display name, sort name, legal name — or a header that is just “Name”.
In review these show as Removed · Looked like personal info · not stored, with Not shown in place of a first value.
Columns removed by what's in them
A harmless-looking header can still hold personal information — a column called “Contact” full of email addresses, say. So we also look at the first 1,000 rows of every column, including ones you might set to Ignore. If at least 60% of a column's filled-in values look like one of these, the column is removed:
| Looks like | For example | Shown in review as |
|---|---|---|
| Email addresses | sam@example.org | Looked like email addresses |
| Formatted phone numbers | (555) 123-4567, 555-987-6543, +1 555 222 3333 | Looked like phone numbers |
| Street addresses | 123 Main St, 45 Oak Avenue, 9 N Elm Rd | Looked like street addresses |
Plain runs of digits such as 5551234567 aren't treated as phone numbers, so numeric IDs are safe. But this check applies to every column: if your constituent IDs are email addresses, that column is removed too, and you'll need to export your CRM's own donor ID instead.
What we keep, and when the original file is deleted
From each imported row we store the transaction ID, constituent ID, date, amount, your type label and the type it's matched to, the capacity rating if you used one, and the values of columns you kept as details. For the upload itself we keep the file name, the column headers, the first value of each column you kept, and the list of rows left out (row number, transaction ID and reason).
The original file is deleted as soon as the import finishes — or as soon as we find it can't be used. A file you never finish reviewing is deleted after 24 hours. You can't download the original from TrueRFM, so keep your own copy. More about what we store: Data, privacy and deleting.
Uploading a file
- Open Upload new file from Uploads, or choose Upload transactions (or Use a different file) on a matrix. Starting from a matrix links the file to it, and the matrix uses it as soon as the import succeeds.
- Make sure Upload a file is selected at the top (the other choice, Connect your CRM, is covered in Connecting your CRM).
- Under What's in this file?, choose transactions or Engagement.
- Drag the file onto Drag your CSV, Excel or ZIP file here, or choose Choose file. The upload starts straight away.
- A progress bar shows the file being sent. Keep the page open until it finishes; you're then taken to the upload's own page.
While we read your file
The upload's page shows Reading your file… while we match your columns, remove personal information, settle the date format and count your type values. The page updates by itself, and you can leave it — the upload waits for you in Uploads with the status Needs review. Remember that an upload you never review is deleted after 24 hours.
No rows are stored while we read: this first pass only looks. Gifts are stored when you choose Import gifts.
The review step
Review is where you confirm what each column is and what each transaction type means. Nothing is imported until you choose the button at the bottom.
Excel files with several sheets
If your workbook has more than one sheet, a Sheet menu appears at the top of review, set to the sheet we read (the first one with data). Choose a different sheet and press the button at the bottom: we read the file again from that sheet and bring you back to review.
Review your columns
The heading tells you how many rows we read, how many columns we kept as details, and how many we removed as personal information. Below it, one line per column:
- Your column
- The header from your file. The date column also has the Read as menu.
- First value
- The first filled-in value in that column, so you can tell what it holds.
- Used as
- What the column becomes: transactionid, constituentid, date, amount, type, capacity (optional), Keep as detail or Ignore.
If you change any Used as (or the sheet), the button reads the file again with your choices before anything is imported — the page says “Changed a column? We'll read the file again first.” You come back to review with fresh first values and type values. Any gift types you matched yourself are kept.
Example: a typical CRM export
An export has the headers Gift ID, Constituent ID, Gift Date, Gift Amount, Gift Type, Fund, Donor Name, Email, Notes. Review shows:
- Gift ID → transactionid, Constituent ID → constituentid, Gift Date → date, Gift Amount → amount, Gift Type → type.
- Fund → Keep as detail.
- Donor Name and Email → Removed, not stored.
- Notes → Keep as detail. If your notes can mention people, change it to Ignore.
Before we can build: problems and notices
If something stops the import, the page lists it under Before we can build: (Before we can import: for an engagement file) when you press the button:
| Message | What to do |
|---|---|
| Choose the column that holds transactionid. (or constituentid, date, amount, type) | No column is used as that. Find it under Your column and set Used as. If the column was removed as personal information, it can't be used — export a different ID. |
| Only one column can be used as date. (or any other role) | Two columns have the same Used as. Set the extra one to Keep as detail or Ignore. |
| Only one column can be used as capacity. | The same, for capacity. |
| Match the remaining transaction type before building. / Match the remaining 3 transaction types before building. | Choose a type for every value marked Choose a type… in Match your transaction types. |
| Choose how dates are written in your file. | We couldn't read any dates in the column used as date. Check that the right column is set to date; if it is, its values aren't in a format we read — fix them in your file and upload it again. |
Some messages are notices rather than problems — they don't stop the import:
- Lots of different type values. The type column has more than 500 different values. That almost always means the wrong column is used as type (a fund or appeal column, say). Check Used as.
Transaction types and matching
Every transaction in TrueRFM is one of eleven types. The type decides whether it counts toward frequency and monetary for your organization type, so every value in your type column needs one before you can build.
The transaction types
| Type | What it means | Counts for nonprofits and government | Counts for businesses |
|---|---|---|---|
| One-time gift | A single gift of money: cash, check, card, stock. | Yes | No |
| Recurring gift | A payment from a monthly or other recurring plan. Each payment is a row. | Yes | No |
| Pledge | A promise to give, at the full amount promised. | No — promises never count; their payments do | No |
| Pledge payment | A payment toward a pledge. | Yes | No |
| Planned gift | A planned or deferred gift, such as a bequest intention. | No — a promise, not money | No |
| In-kind gift | Goods or services, at the value you recorded. | Yes | No |
| Membership | Membership dues or a renewal. | Yes | No |
| Purchase / order | A sale: online, in store, by phone, an invoice. | No | Yes |
| Subscription | A subscription charge or renewal payment. | No | Yes |
| Ticket | An event ticket or registration. | No | Yes |
| Refund / return | Money given back. | Always comes off the amount, whatever its sign in the file, and never counts as a transaction | |
Note: a nonprofit with a gift shop or ticket sales can match those rows to Purchase or Ticket, but they won't count on a nonprofit's matrices. Match them to One-time gift if you count them as giving.
How values are matched for you
Common labels are matched as we read the file. Capitals, spaces and punctuation are ignored, so In-Kind, in kind and IN_KIND all match In-kind gift.
| Type | Labels matched for you |
|---|---|
| One-time gift | Donation, Gift, One-time, Single, Cash, Check, Outright, One-time gift |
| Recurring gift | Recurring, Monthly, Sustainer, Sustaining, Recurring gift, Recurring donation, Recurring payment, Recurring gift payment |
| Pledge | Pledge, Commitment |
| Pledge payment | Pledge payment, Installment, Pledge installment |
| Planned gift | Planned, Planned gift, Bequest, Legacy, Estate gift |
| In-kind gift | In-kind, Gift in kind, GIK, Non-cash |
| Membership | Membership, Member, Dues, Membership dues, Renewal, Membership renewal |
| Purchase / order | Purchase, Order, Sale, Invoice, Online order, In store, POS |
| Subscription | Subscription, Renewal payment, Subscription payment |
| Ticket | Ticket, Tickets, Event, Event ticket, Registration |
| Refund / return | Refund, Return, Chargeback, Reversal |
“Credit” isn't matched for you: some systems use it for a card payment, others for a refund.
Matching the rest
Under Match your transaction types you see every value in your type column, with the most common first: Your value, how many Rows have it, and the type it Matches. Choose a type… means it has none yet. Labels like Grant or Matching Gift aren't matched for you, because organizations count them differently; choose the type that fits how you count them. You can also change a match we made for you.
Example: four values, one to match
| Your value | Rows | Matches |
|---|---|---|
| Online Order | 18,204 | Purchase / order (matched for you) |
| Subscription | 9,850 | Subscription (matched for you) |
| Return | 1,120 | Refund / return (matched for you) |
| Wholesale | 412 | Choose a type… |
Choose Purchase / order for Wholesale and the import can go ahead.
Duplicate transaction IDs
Each transactionid can appear once. If several rows share one, we keep the first of them (the one nearest the top of the file) and leave the others out with the reason “Duplicate transactionid”. IDs are compared ignoring capital letters, so T-1 and t-1 are the same ID.
Duplicates usually mean the export repeated rows (a gift listed once per fund, say) or a refund reused its gift's ID. If the left-out rows matter, fix the IDs in your file and upload it again.
Rows left out of the import
When the import finishes, the upload's page says either “Every row was used.” or how many rows were left out, with a Download left-out rows (CSV) button. The download lists each left-out row by its row number, its transactionid and the reason — never any other values. Row 1 is the first row under the headers.
| Reason | Why |
|---|---|
| No transactionid | The transactionid cell is empty. |
| No constituentid | The constituentid cell is empty. |
| No type | The type cell is empty. |
| Value longer than 100 characters | The transactionid, constituentid or type is over 100 characters. |
| Date not readable | The date is empty or doesn't fit the format chosen for the file. |
| Amount not readable | The amount is empty or isn't a number we read. |
| Duplicate transactionid | An earlier row has the same transactionid. |
Engagement files
An engagement file lists activities, one per row, for RFE matrices. Engagement is the number of activities each person has in the matrix's window, and recency uses whichever is later: their last transaction or their last activity.
- On an RFE matrix choose Upload engagement, or open Upload new file and choose Engagement under What's in this file?.
- Drop the file, review the columns, then choose Import activities.
- An RFE matrix waiting for it scores again once it's imported. You can also pick an imported engagement file when you create an RFE matrix.
Engagement file columns
| Column | What it is | Example | Names we recognize |
|---|---|---|---|
constituentid or customerid | The same ID your transactions use — never a name. | C-004518 | All the ID names above, plus User ID, Attendee ID, Volunteer ID |
date | When the activity happened. Same date formats as transactions. | 2026-03-14 | Date, Activity Date, Event Date, Attended Date, Login Date, Open Date, Engagement Date, Interaction Date, Timestamp, Visit Date |
activity (optional) | What it was, up to 100 characters. | Event | Type, Activity, Activity Type, Event Type, Engagement Type, Interaction Type, Action, Channel, Event |
Review offers donor or customer ID, activity date, activity type (optional) and Ignore. Other columns aren't needed and are never stored, but they're still checked for personal information. Activity types are kept as written; there's nothing to match. Rows without an ID or a readable date are left out and listed in Download left-out rows (CSV).
Note: deleting an engagement file doesn't delete RFE matrices that used it; they score without engagement until you add another.
The Uploads list
Uploads lists every upload in your organization, newest first — files and gifts pulled from a CRM alike. Engagement files are marked · Engagement.
| Status | Meaning |
|---|---|
| Reading… | The file is still arriving, or we're reading it. |
| Needs review | Waiting for you to review columns and types. Deleted if not imported within 24 hours of the upload. |
| Importing… | Gifts are being stored. |
| Imported | Done. Rows imported shows how many transactions (or activities) it holds. |
| Couldn't read | The file couldn't be used. Open it to see why. Nothing from it was kept. |
An upload's page
Choose a file name to open its page. What you see depends on where it is:
- Reading or importing — progress, which updates by itself. While importing it shows a progress bar and the number of rows; you can leave the page.
- Needs review — the review step, with Delete this upload if you're allowed to delete it.
- Imported — how many gifts were imported, how many rows were left out, and buttons to build matrices or go back to the matrix it was uploaded for.
- Couldn't read — what went wrong (see Troubleshooting), “Your file has been deleted. Nothing from it was kept.” and Upload a different file.
Gifts pulled from a CRM have their own page with Refresh and the pull summary — see Connecting your CRM.
Uploads you never review are deleted after 24 hours
An upload that hasn't been imported 24 hours after you started it — still uploading, being read, or waiting in review — is deleted, along with its file. We check every hour. Uploads that were imported, or that couldn't be read, aren't affected.
Building matrices from an upload
When an upload says Imported, its page offers:
- If you uploaded from a matrix, Back to (the matrix's name). The matrix already uses the file and fills in live as people are scored.
- Otherwise, Build named segments from it, or Choose another matrix for any other type.
One upload can feed as many matrices as you like. Not sure which to build? See which matrix answers which question.
Bringing in newer data
A matrix uses one upload at a time. Upload the whole history again, not just the new transactions, and build a new matrix from it. Once nothing uses the old upload, you can delete it. If you'd rather not export files at all, connect your CRM and refresh instead.
Deleting an upload
While an upload is in review, its page has Delete this upload. Imported uploads are deleted from Settings › Data.
Careful: deleting an upload deletes every matrix built from it, with their history. It can't be undone. Matrices still waiting for the upload go back to asking for transactions.
The owner can delete any upload. A member can delete the uploads they added, unless a teammate's matrix is built from one. Full details: Deleting uploads, matrices or everything.
Troubleshooting
The exact messages you might see, and what to do about each.
The file won't upload
These appear on the upload page, under the drop area:
| Message | What to do |
|---|---|
| We can read CSV and Excel files, or a ZIP holding one of them. | Save the file as CSV or Excel (.xlsx). PDFs, Word files and Numbers files can't be read. |
| The file is empty. | Check you chose the right file. |
| Files can be up to 2 GB. Split the file, or ZIP it. | ZIP it (one file per ZIP), or export fewer years at a time. |
| The upload was interrupted. Please try again. | The connection dropped and a piece of the file couldn't be sent after three tries. Try again on a steadier connection, or ZIP the file so there's less to send. |
| The file didn't arrive. Please upload it again. | Upload it again. |
We couldn't read your file
These show as a panel on the upload's page. The file has already been deleted; fix it and choose Upload a different file.
| Title | Detail | What to do |
|---|---|---|
| This ZIP doesn't hold exactly one file | The ZIP file is empty. / The ZIP file holds 3 files. Upload a ZIP with exactly one CSV or Excel file. | Put one file in the ZIP, or upload the CSV or Excel file on its own. |
| No column names | The file is empty. The first row should hold the column names. / None of the workbook's sheets has data. | Make sure the first row holds the headers. |
| No rows we can use | The file has column names but no rows of gifts. | The file only has headers. Check the export. |
| No rows we can use | None of the rows had a transactionid, constituentid, readable date, amount and type. | Every row was left out at import. Usually the wrong column is used as date or amount, or the dates are in a format we don't read. |
| We couldn't read this file | We couldn't read this file. Save it as CSV or Excel (.xlsx) and upload it again. | The file is damaged or isn't really the type its name says. Open it and save it again as CSV or .xlsx. |
| We couldn't read this file | We can read CSV and Excel files. “notes.pdf” is neither. | A ZIP held a file we can't read. Zip a CSV or Excel file instead. |
| Please upload the file again | The uploaded file is no longer available. Please upload it again. / Something went wrong reading this file. Please upload it again. | Upload the same file again. If it fails twice, email support@truerfm.com. |
Stuck in review
- A column I need was removed. Its name or values looked personal (see How personal information is removed). Removed columns can't be brought back. If it's your constituent ID column and the IDs are email addresses, export your CRM's donor ID instead.
- The first values look shifted or wrong. Check the right sheet is chosen, and that the first row of the file holds the headers.
- Dates are read the wrong way round. Change Read as on the date column before you import.
- The button just reads the file again. That happens once after you change a column or sheet. Review the new values and press it again.
- For each message under Before we can build:, see problems and notices.
Fewer gifts than rows
Download the left-out rows and look at the reasons (see Rows left out). The most common causes are a refund or adjustment reusing its gift's ID (Duplicate transactionid), blank constituent IDs on anonymous or batch rows (No constituentid), and a few dates in a different format from the rest (Date not readable).
Advanced: exact parsing rules
CSV and text files
- The delimiter — comma, tab, semicolon or pipe — is detected from the header row.
- Values with the delimiter inside them must be in double quotes, as spreadsheet programs write them:
"$1,000.00". - Every value is trimmed of spaces at both ends; an empty or all-space cell is treated as empty.
- Lines starting with
#are data, not comments, so a# of giftsheader or a#1001transaction ID is read normally. - Headers are trimmed too. A column with a blank header is set to Ignore.
Tip: if accented letters in your type labels or detail values look wrong in review, save the file from Excel as CSV UTF-8 and upload it again.
Excel workbooks
- Without a sheet chosen, we read the first sheet that has a header row; every sheet is listed in the Sheet menu.
- Cells formatted as dates are read as dates, whatever their display format. Other numbers are read as plain numbers with up to 12 decimal places and no thousands separators.
- Cells holding formula errors (
#N/A,#REF!) are read as empty. - IDs stored as numbers lose any leading zeros in Excel itself, before we see the file. Format ID columns as text before you export if your IDs start with zeros.
Header and role rules
- Blank headers → Ignore.
- Headers that look personal → Removed (see the list).
- Each remaining header is lowercased and stripped of everything but letters and digits, then compared with the recognized names. The first column to match a role gets it; later matches for the same role are kept as details.
- Everything else → Keep as detail in a transactions file, Ignore in an engagement file.
- The first 1,000 rows of every non-removed column are then checked for personal values (60% threshold); matches → Removed.
Your changes in review can reassign any column except a removed one. When the type column is changed, type values are counted again; matches you chose yourself are kept for values that are still there.
Date detection
The filled-in dates in the first 1,000 rows of the date column are tried against every format in this order: YYYY-MM-DD, YYYY/MM/DD, MM/DD/YYYY, DD/MM/YYYY, MM-DD-YYYY, DD-MM-YYYY, DD.MM.YYYY, YYYYMMDD, MM/DD/YY. Anything from a T or a space onward is ignored first. A date only counts if its year is between 1900 and 2100. The format that reads the most sample dates wins; on a tie, day-first loses to the others. Day and month may have one or two digits (9/8/2026). Every row is then read with that single format.
Amount parsing
An amount is read as US currency first — dollar sign, thousands commas, a leading minus or accounting parentheses — and failing that as a plain number with a period for decimals. Amounts are stored to the cent.
Type values
- Type values are counted across every row of the file (rows later left out included), which is why Rows can add up to more than the gifts imported.
- Up to 500 different values are listed for matching; past that, review shows the Lots of different type values notice.
- For automatic matching, labels are lowercased and everything but letters is removed before they're compared with the table above.
Row checks, in order
At import, each row is checked in this order, and the first failure is the reason it's left out: transactionid present → constituentid present → type present → none of those three over 100 characters → date readable in the file's format → amount readable. Capacity and detail values never cause a row to be left out; a capacity that's unreadable or not above zero is simply ignored, and detail values over 400 characters are cut to 400.
Duplicates are found after that: among the rows that passed, the first row of each transactionid (by position in the file, ignoring capital letters) is kept.
How rows are counted
“We read N rows” counts every row under the header row. After import:
Example: 12,480 rows
| Step | Rows |
|---|---|
| Rows read | 12,480 |
| Left out: No constituentid | −37 |
| Left out: Date not readable | −12 |
| Rows that passed the checks | 12,431 |
| Left out: Duplicate transactionid | −25 |
| Imported gifts | 12,406 |
The page says “Imported 12,406 gifts.” and “74 rows were left out.” (37 + 12 + 25). Imported plus left out always equals rows read.
Constituent IDs are matched ignoring capital letters too: C-1 and c-1 are the same donor in every matrix.
Large files
- Your browser sends the file in 8 MB pieces, straight to our storage, and retries each piece up to three times before giving up. Nothing about the file is checked in your browser; it's read on our servers.
- The link your browser uses to send the file works for two hours. On a slow connection, ZIP a very large file so it finishes in time.
- If you close the page while the progress bar is still moving, the upload stops. Start again — the unfinished one is deleted after 24 hours.
- Once the file is sent, reading and importing happen on our servers. Large files import in batches with a progress bar, and you can leave the page.
Questions
My export has donor names and emails in it. Do I need to delete them first?
No. Columns whose names or values look like names, emails, phone numbers or addresses are removed the first time we read the file and are never stored. The one thing to watch is free-text columns such as notes or comments, which can mention people in passing — set those to Ignore in review.
Which ID should I use as the constituent ID?
The ID your CRM uses for each donor record — Constituent ID, Donor ID, Account ID or Lookup ID. Use the same kind of ID in every file, so a person is the same across uploads and engagement files. Don't use an email address: that column would be removed as personal information.
How many years of gifts should I upload?
All you have, if you can. Matrices count the last 3 years by default, named segments need more than a year to show movement, and True segments learn more from longer histories.
Should I include soft credits?
No. Every row counts toward its constituent's giving, so a soft credit row would count the same money twice — once for the donor and once for the person credited. Export hard credits only. (When you connect a CRM, soft credits are left out for you.)
Why can't I build until every gift type is matched?
The type decides whether a gift is money received. A value without a type would leave its gifts out of every total without telling you, so we ask you to decide. It only takes a moment: most values are matched for you.
Why were fewer gifts imported than the rows in my file?
Some rows were left out — missing values, unreadable dates or amounts, or duplicate transaction IDs. Choose Download left-out rows (CSV) on the upload's page to see each row number and reason.
How do I update a matrix with newer gifts?
For a matrix, choose Use a different file and upload your full, current export. For a matrix or True segments, build a new matrix from the new upload. Or connect your CRM and use Refresh. See Uploading again with newer data.
Can I combine two files into one upload?
No — each upload is one file, and a matrix uses one upload. Combine the rows into one file before uploading (with the same columns), or ZIP the combined file if it's large. A ZIP with two files in it is refused.
Can I download my original file again?
No. We delete it as soon as the import finishes, so keep your own copy. You can still see the imported gifts in View records on any matrix built from it.
I uploaded a file yesterday and now it's gone. What happened?
It was probably never imported. Uploads that aren't imported within 24 hours of starting — including ones left waiting in review — are deleted with their file. Upload it again and finish the review.
Can a member delete my upload?
Only the owner can delete an upload someone else added. A member can delete the uploads they added themselves, as long as no teammate's matrix is built from them. See owners and members.
My constituent IDs lost their leading zeros. Why?
Excel drops leading zeros from cells stored as numbers, before we ever see the file. Format the ID column as text in Excel (or export to CSV straight from your CRM) and upload again. Mismatched IDs would make one donor look like two across files.
I uploaded my engagement file as transactions. What now?
Delete the upload from its review page (or from Settings › Data) and upload it again with Engagement chosen under What's in this file?. The choice can't be changed after the file is sent.