This article, in many ways, is an extension of my earlier article about importing activities. Many of the principles and key considerations are the same. Rather than repeat the content of that article at length, I'll simply refer you to it where the principles and recommendations are the same.

Initial Considerations

Like with activity records, contributions may only be imported to existing contacts. You can't have new contacts created on the fly -- the contribution must match and be imported to a pre-existing contact. For this reason, you will likely need to import your file as contact records before you can import them as contributions. When doing this, your primary consideration should be the question of how your contributions will match with their corresponding contribution records.

Remember to backup your database before you do a large import! You may also want to run a test import with a small selection of your records to ensure they import as expected, before you do your full import.

In the article on importing activities we discuss the options for matching a contribution to a contact during import, namely:

  • contact ID
  • external ID
  • email

The same options are availale to contribution imports. As with activities, the contact ID and external ID fields provide the most precise control over the matching process. Please review that article for more guidance on best practices and suggestions for using the external ID field to its fullest potential.

Once you've imported your contacts (or know that the contacts will match with existing records), you can begin to import the contribution records.

Importing Contributions

The import contributions tool is found under the Contributions menu. There are several options you must review and configure from this interface:

  • first row contains column headers: most of the time your data file will include the column headers. Make sure to select this option so that you can easily map your fields to native CiviCRM fields.
  • contact type: when importing contributions, you must select the contact type you are importing to. You cannot import to individuals and organizations simultaneously. This may mean you will need to do some work on your data file before you can begin the import process, in order to split it into contact-type specific data sets.
  • import mode: most of the time you are likely to be importing new contributions recors for your contacts. However, CiviCRM provides the option of importing and updating existing contributions. This may be useful if you need to do a very large bulk update of some fields (such as the status field) for existing contributions. If you import and update existing records, you must include the contribution ID in your import file. The import will fail if that field is not present. Also note that you can't mix actions -- you can either insert or update, but cannot have a file that expects to do both (e.g. update when a contribution ID is present, otherwise insert).
  • date format: date formats must be formatted carefully when they are inserted into MySQL databases. Consequently, CiviCRM provides several options for your import format so it can interpret the date accurately and convert it to the correct database format accurately. Make sure all date columns in your file are formatted in the same way.

If you have done contribution imports in the past, you will have noticed an option on the mapping step where you can save your mapping for future use. If you've done that, you will have a field to "Load Saved Field Mapping" available on this first step of the process. Saving a field mapping is a very useful way to streamline your process when you will have multiple imports from a common source (and thus structured in the same way).

Once you've completed the configuration on the first step of the process, submit the form and advance to the next step.

Each column in your import file will be imported to a CiviCRM field (either a core field or a custom field you've previously created). This is done by mapping the fields in the second step. The screen will display your field names (row 1 of your import file), the second row of data, and the field in CiviCRM it should be matched to. Review every field and ensure it is mapped correctly. You don't need to map every column -- you can select the "do not import" option to skip a field if desired.

CiviCRM does have certain requirements for fields that must be present in order to successfully import the file. These are:

  • Contact ID, External ID, or Email: at least one of these fields must be present in order for the contribution to match a contact.
  • Financial Type: this is your classification system for contributions. If you don't recall the available options, or need to create new ones, visit Administer > CiviContribute > Financial Types
  • Total Amount: provide a number (decimal) without the currency symbol.

Provided those fields are present, the records will import successfully. However, you likely will want to include at least a few additional fields in order to have as complete data as possible. For example, you will generally want to include the Receive Date, Contribution Status (defaults to completed), and perhaps the Payment Instrument (check, credit card, etc.). 

Note the option at the bottom of this page to save the field mapping. As noted earlier, that is a very useful way to streamline future imports if you anticipate data coming from the same source in the future.

After advancing to the next step in the wizard you will have a chance to preview your import and then trigger the actual import.

In either or both of those two steps, CiviCRM will report back any data problems it may have found with your import file. The preview step will check things like date format. The actual import step will report back if it cannot match the contribution record to a contact. In either case, the file provided is very useful, as it includes a copy of the row that was problematic and details regarding the column with issues and the nature of the problem. In most cases, you can actually use this error file to fix your data and reimport those rows. Simply delete the first two columns that were prepended to detail the error, fix the data causing the problem, and import using that file.

After importing, be sure to review your records and confirm they were handled as expected.