Skip to content

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:

  1. First Name
  2. Last Name
  3. Entity Name
  4. Type
  5. Trading Name
  6. Tax No
  7. ID Reg No
  8. ID Type
  9. Country of Issue
  10. Email
  11. Cellphone
  12. Address 1
  13. Address 2
  14. City
  15. Province
  16. Post Code
  17. Country
  18. Reference
  19. Receipt No
  20. Receipt_Method
  21. Amount
  22. Donation Date
  23. Project
  24. Certificate No
  25. Description
  26. Fundraiser (optional)
  27. 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 CD0000796712 is 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.