You can import Donations into Spektrix using the Importer. Using the Importer can save you time if you need to process multiple donations taken outside of Spektrix.
Your organisation may process Donations outside of Spektrix for reasons such as:
- importing historical gifts from outside your Spektrix system
- Donations processed through a Tap to Donate station
- Donations processed through an external processor
- Logging consolidated payments from third-party giving platforms (like The Big Give in the UK or Canada Gives)
The concepts in this article require a basic understanding of imports and donations. Before reading this article, make sure you’re familiar with:
How does importing donations work?
You can import donations into Spektrix using a transaction import. This means that each record you upload will generate an Order within Spektrix, which contains the details of each Donation against a Customer Record.
TIP: You can create new Funds using the import. Alternatively, you may wish to set up any new Funds before making your import.
To import Donations into Spektrix, you’ll need to compile the data about each Donation into a CSV file. You’ll then upload the CSV using the importer to add the data to your system.
The CSV file you upload must be formatted exactly as outlined in this article.
Before uploading your import, you’ll need to check your data. If your data doesn’t match the required format, then incorrect data can be uploaded to your system.
WARNING: You’re responsible for the data you import and for fixing any mistakes which result from the import. Spektrix can’t reverse any imports you upload.
Once you’ve prepared your CSV file, you can upload it to Spektrix to validate and then import it using the Importer.
Successfully imported data will be available alongside your other data in Spektrix in the Sales and Opportunities interfaces, and in Reports and Customer Lists.
After uploading your import, you should check your system to ensure that the data has been imported as you expect.
If you need to re-import some rows of your data because they have failed, take out the successfully imported donations from your file. If you don’t remove already successfully imported Donations then you will import duplicate Donations.
How to import Donations
Work through the following steps in order to import donation payments into Spektrix.
1. Prepare your CSV file
Transform your data into the correct format before you upload your import.
Use a CSV editor program such as Excel or a third-party tool like Rons Data Edit (if approved by your IT team). Make sure that the CSV editor program you are using can save files in the UTF-8 format.
If you're using a formatted report from Spektrix as the basis of your CSV file, you must still check the data and ensure it’s in the correct format for the import.
REMINDER: Your CSV File must be formatted exactly as outlined in this article to import successfully.
Your CSV file
For an import to be successful, your CSV file must meet the following standards:
- All required fields must be populated with data. Read the Required Data Fields section of this article for details about each of the required fields for a donation import.
- Each column name must match the correct column name exactly, including capitalisation and spaces. Read the Required Data Fields section of this article for details about each of the column names.
- Data must match the required format for the field type. For example, you cannot import free text into a Yes/No field. For more information, read the Field Types section of the Introduction to the Importer.
- Each CSV must be in the UTF-8 encoding format. Read more about UTF-8 encoding in the Introduction to the Importer.
Required Data Fields
In the table below, we’ve outlined the different data fields that can be included in Donation imports and whether they are required.
If a field that isn’t required is left blank, then no data will be imported into this field.
| Column Name | Description | Required |
| OwnerSpektrixId |
Enter the Spektrix Customer Record ID that you’d like to import the donation against. Transactions can only be imported against existing customers. This field is only required if an email address is not supplied.
|
Yes, if no email address is supplied |
| EmailAddress |
Enter the customer’s email address. Transactions can only be imported against existing customers. This field is only required if an OwnerSpektrixId is not supplied.
|
Yes, if no OwnerSpektrixId is supplied |
| TransactionDate |
Enter an Accounting Date for the donation using the correct format (yyyy-mm-dd). If left blank, the Accounting Date will default to the Date Transaction Confirmed. The Date Transaction Confirmed field will always be the date of the import, regardless of the Accounting Date.
|
Yes, but can be left blank |
| Amount |
Enter the Donation amount. This value must be greater than or equal to zero.
|
Yes |
| FundName |
Enter the name of the Fund you’d like the Donation to go towards. If there is no Fund of the same name (case sensitive) then a new Fund will be created. Your imported Donation will be attributed to the default Campaign associated with the Fund you choose.
|
Yes |
| TributeType |
Enter the Tribute type. If there is no Tribute type of the same name (case sensitive) then a new Tribute type will be created. This field is required when Tribute Name is set.
|
No |
| TributeName |
Enter the Tribute name. This field is required when Tribute type is set.
|
No |
| RecognitionName |
Enter the Recognition Name. This field cannot be set when IsAnonymous is Yes.
|
No |
| IsAnonymous |
Enter Y to make this donation anonymous. This field cannot be Yes when Recognition Name is set.
|
No |
| GiftAidClaimable |
For UK organisations, enter Y if the Donation is Gift Aid claimable. For more details, read the Gift Aid section of this article.
|
No |
| GiftAidClaimed |
Enter Y if the Gift Aid has already been claimed outside of Spektrix. Enter N if the Gift Aid has not yet been claimed and you want to include it in future Gift Aid claims through Spektrix. When GiftAidClaimable is set to Y, the value for GiftAidClaimed must be set to either Y or N. Leave this value blank if GiftAidClaimable is set to N. For more details, read the Gift Aid section of this article.
|
No |
| PaymentReference |
Enter a payment reference if you have one.
|
No |
| OrderNote |
Enter any free text you’d like to import into the Blue Pop Up Note attached to the Order.
|
No |
| OrderCustomField:{CustomFieldName} |
If you need to import any custom Order Attributes, then amend and populate this field. For more details, read the Custom Fields section of this article.
|
No |
Gift Aid
For organisations in the UK, you can indicate whether the Donation you are importing is eligible for Gift Aid, and whether the Gift Aid has already been claimed.
REMINDER: Gift Aid is only claimable where there is a valid Gift Aid Declaration on the Customer Record.
- GiftAidClaimable
As a default, imported donations are opted out of Gift Aid. This means that if you leave the column blank, enter N, or don’t include the column then the Donations you import won’t be eligible for Gift Aid claims.
If you enter Y in the GiftAidClaimable column, then the Donation becomes eligible for Gift Aid claims.
WARNING: Keeping an accurate record of Gift Aid is important to avoid claiming Gift Aid on a donation twice. If you mark a donation as Gift Aid Claimable then it is not possible to remove this from future Gift Aid claim reports without returning and repurchasing the Donation.
- GiftAidClaimed
This field can only be set if GiftAidClaimable is set to Y.
If GiftAidClaimable is set as N or not included, the donation will not be Gift Aid claimable, and the GiftAidClaimed field cannot contain a value.
If you enter N in the GiftAidClaimed column, then the Donation you are importing will be included in future Gift Aid claims.
If you enter Y in the GiftAidClaimed column, then the Donation you are importing won’t be included in future Gift Aid claims.
In Spektrix, a claim will appear to have been generated and successfully processed. This will not submit your claim to HMRC. A record will be created for every line in the import file. You can view these “claimed” records under the Admin Interface > Other > Gift Aid Claims.
WARNING: By entering Y in the GiftAidClaimed column, you’re indicating that your gift aid has been processed and claimed outside of Spektrix. In Spektrix, it will appear as though your Gift Aid has been claimed through Spektrix.
Custom Fields
The Order Custom Field column can be used to import custom OrderAttributes.
To add a custom field, use the OrderCustomField:{CustomFieldName} column name.
In the column name, replace {CustomFieldName} with the exact name of your Order Attribute.
REMINDER: Attribute names are case sensitive and must match exactly (including spaces) to be successfully imported. You'll also need to remove the curly brackets. Do not add a space between the colon and the start of your Attribute name.
For example, if your Order Attribute is "Is Direct Debit” then your column header would be:
OrderCustomField:Is Direct Debit
If your custom Order Attribute is a dropdown list, then the data in the column must match the dropdown values exactly.
For example:
| OrderCustomField:Is Direct Debit |
| Yes |
| No |
WARNING: If you have Order Attributes set up on your system which are marked as required, you’ll need to import these alongside your data. Your import will fail if you do not supply values for required Attributes.
Example
Click the image below to see a detailed example of a Donation Import. This example has been formatted correctly with all the required headings and is ready to be uploaded.
REMINDER: Don’t forget to save your CSV in the UTF-8 encoding format.
2. Validate your data
The Importer is found in the Settings interface.
TIP: To access the Settings Interface, you’ll need the Settings Administrator Role. If you don’t have this Role, ask the Settings Administrator in your organisation to add this Role to your User Account.
Each import type has two processes that can be run against it: Validate and Import.
All imports must be validated before they are imported.
The validation process checks the data in the input file against validation rules to identify any issues in the CSV file. It does not check against data already in Spektrix (for example, customer data), so you may still get data-specific errors when running your import.
WARNING: Do not run your import until you have received a successful validation CSV.
How to use the Validator
REMINDER: CSV files must be in the UTF-8 format and contain all of the required information for your import.
Once you’ve clicked Run Validator, you’ll see a Job Submitted icon in the top left of the screen:
Hover your mouse over the green check mark and click to download the CSV file to see the results:
How to read the validation document
The validator will give one of two types of responses:
- No validation error found
If the validation is successful, the CSV will contain a message which reads: Validation completed successfully.
- Validation error found
If the validation is unsuccessful, the CSV will contain a message explaining the failure.
For example: Error processing record 5. No matching customer found for owner.
In this example, the customer's email address does not match an existing Customer on the system.
Another example of a failed validation error message is:
‘Gift Aid Claimed' must be empty when 'Gift Aid Claimable' is false.
In this second example, the validation failed because you cannot mark a donation as gift aid claimed when it is not claimable.
How to avoid common errors
Below we’ve listed some tips that can help you avoid common errors:
- Always check your data. If possible, we recommend working with another member of your team to perform the check.
- If you use Excel to edit your CSV files, you’ll need to set the date format to yyyy-mm-dd every time you open the file. Even if you save the file with the correct date format, when you open the file, you’ll need to update the date format again.
- Remember to save your file in the CSV UTF-8 format.
- If you need to re-import some rows of your data because they have failed, take out the successfully imported donations from your file. If you don’t remove already successfully imported Donations then you will import duplicate Donations.
- If you’re using Excel to create your import file, errors do not reference the header row. This means that the number of the error will not correspond directly with the row number in Excel. For example, “Error processing record 24” may refer to Row 25 of your Excel file.
3. Import your data
If your CSV file passes validation, then you can continue to import the file.
REMINDER: A successful validation of your CSV file doesn’t always lead to a successful import of your data.
How to run an Import
-
Select the Import Type: Donations
-
Click Import:
-
Complete the Import CSV details:
- Foreign Id Customer Custom Field Name: Leave blank
- Foreign Id Order Custom Field Name: Leave blank
- Upload the CSV file: Click select file and browse to the location on your computer where the CSV file is saved
After clicking Run Importer, you’ll see a pop up asking you to confirm the number of rows in the import file:
Click Confirm to continue with the import, or click Cancel to go back.
Once you’ve clicked Confirm, you’ll see a Job Submitted icon in the top left of the screen:
Hover your mouse over the green check mark and click on the link to the CSV file to download and see the results:
You’ll also receive an email notification to let you know the import is complete. This will be sent to the email address registered to your User Account.
WARNING: Download and review the import results file before attempting to re-upload an import.
Import results file
A CSV report will be generated and available to download with the result of your import.
If the import is successful, you’ll see Import completed successfully:
If the import fails, you’ll see a message with an error reason.
For example: Error processing row 1. Date not set on required field ‘TransactionDate’.
The CSV report will contain a row for each record that had an error.
Each row explains:
- On what record the error occurred
- The details of the error
- The contents of the object that caused the error (in a single cell, with line breaks between properties)
This file only lists errors. Any rows not listed will have been imported successfully.
Depending on the error in the import results you may want to amend the data and re-attempt to import for those specific rows. If you’re re-attempting an import, remove any successfully imported donations from your file.
4. Check your data
Once you’ve completed your import, we recommend spot-checking your imported donations to ensure the data is being returned as you expected.
This is an example of how an Imported Donation might look in the Sales Interface:
Choose a few of the donations you have imported and check that the following information is accurate:
- The Donation amount
- Transaction and Accounting Dates
- Gift Aid status (if applicable)
To look at an overview of multiple Donations, run the Donations Report with a custom Criteria Set of Transaction Date: today.
Troubleshooting Donation Imports
Below we’ve listed some of the common errors which can occur when importing Donations and how to troubleshoot them.
- Payment Type cannot be inactive: Imported payment
The Imported payment payment type is created automatically on your first import. It must remain active and with no authorisation required. If an admin changes these settings, this can cause future imports to fail.
Go to the Admin Interface and check whether the Imported payment payment type is active. If it's been deactivated, reactivate it before running the import.
- Invalid date. Dates must be in the format yyyy-MM-dd
Reupload the import with the correct date format. If you use Excel to edit your CSV files, you’ll need to set the date format to yyyy-mm-dd every time you open the file.