Importing historical certificates via CSV¶
In short: Upload a CSV or Excel file of certificates you issued elsewhere, map your columns to ActiveDonor's fields, and click Import — ActiveDonor creates the donors, receipts and certificates in the background. Files must be ≤5 MB and ≤3,000 rows. The most recent completed import can be rolled back unless any of its items are already in an IT3(d) submission.
Overview¶
The certificate importer lets you bring existing Section 18A records into ActiveDonor from a spreadsheet — for example certificates you issued in a previous system before moving to ActiveDonor. You upload a CSV or Excel file, map your columns to ActiveDonor's fields, and ActiveDonor creates the donors, receipts and certificates in the background.
This is for historical records you already issued. To create new certificates from donations captured in ActiveDonor, issue them normally — see Issuing a single Section 18A certificate.
Before you start¶
You'll need:
- The Manage Certificates permission.
- Your file as CSV or Excel (
.csv,.xlsx,.xls). - A file that's 5 MB or smaller and contains 3,000 rows or fewer. Split larger files into chunks and upload them one at a time.
- One donation per row; donors are grouped automatically.
💡 Tip: Download the official template so your columns line up — the import page offers "Use this Excel import template" and a "Help Doc: How to import certificates". Matching the template makes column mapping automatic.
The template columns¶
The import template uses these column headings, in this order:
- First Name
- Last Name
- Entity Name
- Type
- Trading Name
- Tax No
- ID Reg No
- ID Type
- Country of Issue
- Cellphone
- Address 1
- Address 2
- City
- Province
- Post Code
- Country
- Reference
- Receipt No
- Receipt_Method
- Amount
- Donation Date
- Project
- Certificate No
- Description
- Fundraiser (optional)
- Cat 1 (optional)
Fundraiser and Cat 1 are optional. If your file already uses the headings Cat 2 to Cat 12, those are read too.
You don't have to use these exact headings in your own file — on the next screen you map each of your columns to the right field — but matching them makes the mapping automatic.
Importing the file¶
Step 1: Open Import Certificates¶
Open the Import Certificates page. If you don't have any certificates yet, the empty Section 18A page offers a shortcut — click the Import from Spreadsheet button (next to Get Started with Receipts) to jump straight here.
Step 2: Upload your file¶
In the Certificate Uploader panel on the left, choose your file (accepted: CSV, Excel .xlsx, .xls) and click Upload.
Step 3: Map the columns¶
ActiveDonor reads the file and shows the Import Preview: how many Columns it found and how many Donors (rows). For each column you see your data and a dropdown to choose which field it maps to (the dropdown lists all the template fields plus an option to ignore a column). ActiveDonor pre-selects a match where your heading matches a template field. Check that every column points to the correct field — the on-screen instruction is "Check if your columns match up with the correct header."
Step 4: Import¶
Click Import. The file is queued and processed in the background.
📌 Note: Only one import can run at a time. While one is in flight the page shows "Import in progress" and refreshes itself; you can upload another once it finishes.
Step 5: Check the result¶
When it completes, the import appears in Import History with the number Imported, the number Skipped, and a status.
How rows are handled¶
- Rows without a Certificate No. The donor and receipt are still imported. The certificate stage is marked as skipped (shown as
-in the results file), not failed. - Receipt numbers with a letter prefix. A Receipt No like
CD0000796712is kept as receipt number 796712 (the letters and leading zeros are dropped). A value that isn't digits, or letters followed by digits, fails the row with the message "Row N: Cannot issue Receipt - Receipt No '…' is not a usable receipt number (expected digits, optionally after a letter prefix, e.g. CD0000796712, up to 2147483647)". A blank Receipt No gets the next receipt number. - Same donor, same day, same amount. Two donations with the same donor, date and amount stay separate when they have different Certificate No values (for example two R50 raffle tickets on one day). Rows with the same certificate number for the same donor are combined onto one certificate.
- Messy email or cellphone values don't fail a row. ActiveDonor keeps the first usable phone number, moves an email address found in the cellphone column to the email, and drops anything it can't use. Each change is recorded as a warning in the results file with the original value, for example Cellphone "0312601111/3305" imported as 0312601111.
- Certificates already sent to SARS are never changed. If a row would add a receipt to a certificate that is already in an IT3(d) submission, that row's certificate stage fails with "Certificate #N is already in an IT3(d) submission and cannot be modified by an import".
- Fundraiser must be the fundraiser's ActiveDonor user ID. It is set on new donors, and on existing donors only when they have no fundraiser yet. An unknown ID is a warning, not a failure.
- Cat 1 to Cat 12 are tag names. Missing tags are created and added to the donor. A donor that appears on several rows gets each tag once.
Import History and status¶
Each import on the Import History table shows a date, the file name, the Imported and Skipped counts, and a Status:
| Status | Meaning |
|---|---|
| 🟢 Completed | Finished successfully. |
| ⏳ Processing | Currently running. |
| ⏳ Queued | Waiting to run. |
| 🟡 Partial | Some rows imported, some skipped. |
| 🔴 Failed | The import failed. |
| ↩️ Rolled Back | The import was undone (see below). |
For a Completed import you can download a results spreadsheet to see exactly what happened with each row.
Rolling back an import¶
If an import was wrong, you can roll it back to undo it.
⚠️ Important: Rollback "will PERMANENTLY DELETE all donors, receipts, certificates, and certificate PDFs from this batch. Receipt and certificate numbers will be reset. This action cannot be undone."
Rules:
- Only the most recent completed import can be rolled back. To undo an older one, roll back the more recent import(s) first.
- Rollback is blocked if any item is part of an IT3(d) submission. Once a certificate from the batch has been submitted to SARS, the batch can't be rolled back. Revoke and re-issue individual certificates instead.
- You can only roll back imports you started.
- Rolling back also removes the tags the import added to its donors. Donor numbers are not reset, so gaps may appear.
When it succeeds you see "Import #N rolled back. All donors, receipts, and certificates from this batch were permanently deleted. Receipt and certificate numbers reset to pre-import values. (Donor numbers are not reset - gaps may appear.)"
Field reference (key columns)¶
| Column | Purpose |
|---|---|
| First Name / Last Name | The donor's names (for a person). |
| Entity Name | The organisation name (for an entity donor). |
| Type | Donor type (Individual, Company, CC, NPC, Trust, Association, Estate, etc.). |
| Tax No | Donor's SARS tax reference number. |
| ID Reg No | Donor's ID or registration number. |
| ID Type | ID or Passport (for individuals). |
| Receipt No | The original receipt number for the donation. |
| Receipt_Method | How the donation was made. |
| Amount | The donation amount. |
| Donation Date | The date of the donation. |
| Project | The project the donation belongs to. |
| Certificate No | The original certificate number. |
| Description | Free-text description of the donation. |
| Fundraiser | Optional. The ActiveDonor user ID of the donor's fundraiser. |
| Cat 1 (to Cat 12) | Optional. Tag names to add to the donor. |
Common issues & solutions¶
| What you see | What it means | How to fix it |
|---|---|---|
| "The uploaded file contains N rows, which exceeds the 3,000-row import limit." | The file is too long. | Split it into chunks of 3,000 rows or fewer and upload one at a time. |
| The file was rejected on upload. | Wrong format or too large. | It must be a .csv, .xlsx or .xls file and 5 MB or smaller. |
| "No data found for preview." | ActiveDonor couldn't detect valid columns or data. | Make sure the first row has column headers with data below them; download the template for reference. |
| Rows were Skipped. | Some rows were missing required details or duplicated existing records. | Download the results spreadsheet to see why, fix them, and re-import only those rows. |
| "Only the most recent completed import can be rolled back. Please roll back the more recent import(s) first." | A newer completed import exists. | Roll back the newer import(s) first. |
| "This import cannot be rolled back because one or more certificates or donors from it have been included in an IT3(d) submission to SARS." | Part of the batch is already with SARS. | Revoke and re-issue individual certificates instead. |
| "You can only roll back imports you started." | Another user ran this import. | Ask the user who ran the import to roll it back. |
| "Certificate #N is already in an IT3(d) submission and cannot be modified by an import" (in the results file) | The row tried to add a receipt to a certificate already sent to SARS. | Leave that certificate as it is. If it's wrong, revoke and re-issue it. |
| "Row N: Cannot issue Receipt - Receipt No '…' is not a usable receipt number …" (in the results file) | The Receipt No isn't digits, or letters followed by digits (for example 12.5 or N/A). |
Correct the value or leave it blank to get the next receipt number, then re-import that row. |
| The rollback button is disabled. | It's not the most recent import, or an item is already with SARS. | Roll back newer imports first; if an item is in an IT3(d) submission, the batch can't be rolled back. |
FAQ¶
Can I bring in certificates from my old system? Yes — that's what this importer is for. Upload a CSV/Excel of the historical records and map the columns.
How big can the file be? Up to 5 MB and 3,000 rows. Split larger exports and upload them one at a time.
Can I undo an import? Yes — roll back the most recent completed import. This permanently deletes everything it created and resets numbering, and is blocked if any item is already in an IT3(d) submission.
Can I import a donation that has no certificate number? Yes. The donor and receipt are imported and the certificate is skipped, so you can issue it later.
Can I set tags or a fundraiser during the import? Yes. Add a Cat 1 column (and Cat 2 to Cat 12 if you need more) with tag names, and a Fundraiser column with the fundraiser's ActiveDonor user ID.
Do my column headings have to match the template exactly? No — you map columns on the preview screen. Matching the template just makes the mapping automatic.