How to create custom donation fields

Custom fields support the collection of key data points not available in standard NationBuilder fields. This feature is relatively complex to implement. If custom fields have not been enabled in your nation, please read the introduction to custom fields HOWTO for information on accessing them. 

Custom donation fields are added to donation records, while custom people fields are added to a person's profile. Below is information on creating custom donation fields, adding that information to profiles, and searching those fields.


Custom donation fields or people fields?

Since you can include both types of fields in donation pages and donor imports, it's important to understand the difference between them. If you want to store information that is connected to a specific donation, use custom donation fields. If you want to store information that persists on a person's profile, use custom people fields. Custom donation fields can be used to allow a donation to be made in memory of an individual. They can also be used to comply with campaign finance laws.

People are more likely to complete a donation when the information requested is minimized. Therefore, we recommend using custom donation fields extremely sparingly.

For example, if you are running for office in New York City, senior officers of businesses who do business with New York City need to report the agency they are doing business with and business category. This data needs to live on the donation in case the donor's employment changes. This way, the record of who the donor's employer at the time of her donation is complete. Please note: if you require the standard employment fields on a donation, that information will be stored with the donation and it will update the person's profile. The employer information persists with the donation even if it is subsequently updated in the donor's profile, allowing you to retain accurate financial records. 


Create custom donation fields

Custom donation fields can be created from Settings > Defaults > Custom fields > Donations. 

create custom donation fields

If you're familiar with creating custom people fields, creating custom donation fields works the same. Be sure you are on the "Donations" tab in order to create custom donation fields. 

1. Define the field name. (Required)

2. Create a slug for the field - no spaces can be included in a slug and it cannot be changed later. (Required)

3. Decide what type of field to create. The options are text, number, checkbox, or multiple choice. (Required)

4. If you are creating a multiple choice field, create options. (Required for multiple choice fields)

5. Click the "Create field" button.

Once a custom field is created:

  • the slug cannot be changed
  • the field type cannot be changed
  • if you delete the field, all stored values for that field will also be deleted
  • by default, the name given to a custom donation field will appear on your donation page

You can create up to 100 custom people fields and up to 100 custom donation fields.

Field type Parameters
Text Free text field, default is blank
Number Up to eight digits to the right of the decimal, i.e. 0.12345678 and default is 0.0 
Check box Default is unchecked
Multiple choice Unlimited options, each option up to 100 characters, and default is no choice selected

Once created, custom people fields will be listed at Settings > Defaults > Custom fields > People directly below the area to create a new field.

For example, here is a list of fields I created:

example custom donation field list


Edit custom fields in a donation

You can edit custom fields in an existing donation. There are two ways to view existing donations: from the finances tab in a person's profile or from Finances > Donations > Listing. Click the edit icon to add custom field information. You'll need to go to the custom fields tab to edit them.

 edit_donation_select_custom_fields.png

donation_custom_fields.png


Import custom fields

Donation custom fields can only be imported with donation imports. Since you can import both signup and donation information during a donation import, both people and donation custom fields can be imported. Note that people custom fields will be listed within the Signup section of the import.

  • When mapping your fields for import, the system will validate that custom number fields are numbers - you won't be able to complete the import if you try to import text into a number field
  • Responses to a multiple choice field must already exist as options for the field. If you import a response that doesn't exist for a multiple choice field, the profile will not be updated for that field and no error message will appear.
  • Checkbox fields can be updated with the following:
    • check the box: true, yes, t, y, or 1
    • keep the box unchecked: false, no, f, n, or 0
    • import is case insensitive, so tRue, TRUE, and true will all result in the box being checked.

Filter options

In the Finances section, click the filter button filter_transactions.png.

Click on "Add criteria." In the Custom Field category, you will see all donation and people custom fields. The way you can search the field depends on its type.

Field type Search options
text is, is not, exists, does not exist
number is, is not, is between, is greater than, is greater than or equal to, is less than, is less than or equal to, exists, does not exist
check box is, is not
multiple choice is (select option), is not (select option), exists, does not exist

If you search within a text field, the data in the field must match your wording in the filter exactly and it is case sensitive. For example, if I was searching for the response "Susan B. Anthony," people who had responded "susan b anthony" would not be included in the filter results. 

When targeting people in the People section, you cannot use custom donation fields as criteria.


How to request custom donation fields on donation pages

Introduction to custom fields

How to create custom people fields

How to request custom people fields on webpages

Subnations cannot create custom fields if their field architecture is synced

Liquid variables available in email

How to import

How to filter

If you’re unclear on how this feature works, please ask a question. If you would like to see changes to this feature, please submit a suggestion.