Donation Fields API

The Donation Fields API is provides a powerful, flexible way to add, remove and edit your donation fields.

What are donation fields?

Donation fields are any bits of information about a donation that are available for you to use. As an example, here are some of the fields available by default:

first_name – Get the first name of the donor.
last_name – Get the last name of the donor.
amount_formatted – Get the donation amount, formatted according to your site’s currency settings (e.g. $50.00).
date – The date that the donation was made.
gateway_label – The payment method the donor used.

How do I get the value for a particular donation field?

You can get the value of any donation field through the donation’s Charitable_Donation object.

The first step is to get a Charitable_Donation object:

$donation_id = 123; // Replace with your Donation's ID.
$donation    = charitable_get_donation( $donation_id );

Next, you can get the field’s value by calling get() on the object, as you can see in the examples below:

$first_name = $donation->get( 'first_name' );
$date       = $donation->get( 'date' );
$gateway    = $donation->get( 'gateway_label' );

To put it all together:

$donation_id = 123;
$donation    = charitable_get_donation( $donation_id );
$first_name  = $donation->get( 'first_name' );

How do I add a new field to my donation form?

Adding a new field is a two-step process.

First, you will create a new Charitable_Donation_Field object which will define your field’s parameters: its label, the type of value it stored, how it should be included in the donation form (if at all), whether it should be added to the Donations export file, and more.

Next, you add this field to the Charitable_Donation_Field_Registry class, which provides a way to store and retrieve donation fields.

Let’s see how this works in an example:

/**
 * Create a callback function on the `init` hook, where we
 * can register our donation field.
 */
add_action( 'init', function() {

    /* Create the `Charitable_Donation_Field` object. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'My Custom Field' ),
            'data_type'      => 'meta', 
            'donation_form'  => array(
                'type'       => 'text',
                'required'   => false,
                'show_after' => 'phone',
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array(
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Get the `Charitable_Donation_Field_Registry` instance. */
    $fields = charitable()->donation_fields();

    /* Add the new field. */
    $fields->register_field( $field );
} );

In the example above, we have created a new field with a key of my_custom_field. Here’s what its defined parameters mean:

Its label is “My Custom Field”. This is what will be used in the donation form, in the admin donation details area and in the donations export as the column header.
Its data type is meta. This means that it will be stored as a meta field specific to that donation.
It is set up to be shown in the donation form, right after the phone field. It’s an optional field.
It will also be added to the admin donation form.
When viewing the details for the donation, you will be able to see what the donor entered for this field in the “Donation Details” section.
When you download a donations export, a new “My Custom Field” column will be added, showing what donors entered for this field.
A new email tag has been created for this field, so you can easily include it in donation-specific emails, like the Donation Receipt (for donors), or the Donation Notification (for administrators).

This is a relatively simple example, but it achieves a lot. Click here for a more detailed breakdown of all the available parameters when creating Charitable_Donation_Field objects.

How do I change an existing donation field?

To change an existing donation field, you first retrieve the field from the Charitable_Donation_Field_Registry, and then update the field value.

To update the field value, we can call set() on the field, or use the magic setter.

/**
 * Create a callback function on the `init` hook, where we
 * can start changing the donation field.
 */
add_action( 'init', function() {

    /* Get the Donation Field Registry object. */
    $fields = charitable()->donation_fields();

    /* Get the field we want to change. */
    $field  = $fields->get_field( 'phone' );
    
    /**
     * Change #1: Make it a required field (uses set()).
     * Change #2: Change the label (uses magic setter).
     */
    $field->set( 'donation_form', 'required', true );
    $field->label = 'Phone Number';
} );

For more information about how to update field arguments, see the detailed reference for those class methods:

Charitable_Donation_Field::set()
Charitable_Donation_Field::__set() (magic setter).

How do I add a field to a specific campaign’s donation form?

If you want a new or existing field to only show for certain campaigns, you can do this by adding a new function which controls whether the field shows in the donation form.

If you are adding a new field, you will first to create the donation field, so follow those steps first.

Now you can hide the field you registered from all donation forms other than the one you want it to show on:

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {

    /* If the field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'my_custom_field', $fields ) ) {
        return $fields;
    }

    /* Match any campaign that DOESN'T have a slug of 'special-campaign' */
    if ( 'special-campaign' !== $form->get_campaign()->post_name ) {    
        unset( $fields['my_custom_field'] );
    }
    
    return $fields;
}, 10, 2 );

What’s happening here?

We only want the my_custom_field field to show on the campaign with a slug of ‘special-campaign’.
The field will show in all campaigns by default, so our code checks if the campaign doesn’t have a slug of ‘special-campaign’ and then removes it.

You can change the condition under which the field is shown. For example, you can change the field to only show for campaigns in a certain category, or for campaigns that have a specific parent campaign (i.e. fundraisers for one of your peer-to-peer fundraising campaigns).

How do I change a donation field for a particular campaign?

The approach used above to show a field on a particular campaign can be adapted to change a donation field for a particular campaign.

For example, if you only want to accept donations from donors in a specific country for a certain campaign, you can achieve that with the following code:

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {
    /* If a country field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'country', $fields ) ) {
        return $fields;
    }

    if ( 'south-africa-only' === $form->get_campaign()->post_name ) {
        $fields['country']['options'] = array(
            'ZA' => 'South Africa',
        );
    }	

    return $fields;

}, 10, 2 );

This code will make it so that the campaign with a slug of ‘south-africa-only’ will only display South Africa as a valid country option.

How do I make a donation field show based on user input?

The previous two examples showed how to add / change donation fields based on the donation form’s campaign. But what if you want to show or hide a field based on user input?

Handling this requires a different approach, using Javascript. If you are a confident developer, you can add this through a new Javascript file, but in the example below we will use the wp_add_inline_script function to add our custom Javascript without needing to create, register and enqueue a new script.

In the example below, we are only showing our custom field, my_custom_field, when the donor is from the United States:

add_action( 'wp_enqueue_scripts', function() {
    wp_add_inline_script( 'charitable-script', "
        jQuery('body').on('charitable:form:loaded', (event, donationForm) => {
            var countryField = donationForm.get_input('country');
            function toggleCustomField() {
                donationForm.get_input('my_custom_field').parent().toggle('US' === countryField.val());
            }
            countryField.on('change', toggleCustomField).trigger('change');
        });
    " );
} );

Full list of default donation fields

The following fields are added by Charitable and its extensions:

Key	Description
`donation_id`	The donation ID
`first_name`	The donor’s first name.
`last_name`	The donor’s last name.
`donor`	The donor’s full name.
`email`	The donor’s email address.
`donor_address`	The donor’s full address, formatted.
`address`	The donor’s first address field.
`address_2`	The donor’s second address field.
`city`	The donor’s city.
`state`	The donor’s state.
`postcode`	The donor’s postcode.
`country`	The donor’s country.
`phone`	The donor’s phone number.
`campaigns`	The campaign that received the donation.
`campaign_categories_list`	The categories that the campaign is in.
`amount_formatted`	The donation amount, formatted according to your currency settings.
`date`	The date of the donation.
`time`	The time the donation was made.
`status`	The donation status. This returns the raw value of `post_status`.
`status_label`	The donation status as a more readable label.
`donation_gateway`	The payment gateway used for the donation.
`gateway_label`	The payment gateway as a reader-friendly string.
`donation_key`	The unique donation key.
`gateway_transaction_id`	The transaction ID for the donation in the payment gateway that was used (i.e. PayPal, Stripe).
`test_mode`	Whether the donation was made in test mode.
`donation_summary`	A readable summary of the donation, listing the campaign receiving the donation & the amount donated.
`contact_consent`	Whether the donor gave their consent to be contacted.
`cover_fees`	Whether the donor covered fees. Added by Fee Relief.
`fee_amount`	The amount of processing fees paid by the donor. Added by Fee Relief.
`fee_amount_formatted`	The amount of processing fees paid by the donor, formatted according to your currency settings. Added by Fee Relief.
`total_donation_with_fees`	The total donation amount including processing fees. Added by Fee Relief.
`total_donation_with_fees_formatted`	The total donation amount including processing fees, formatted according to your currency settings. Added by Fee Relief.
`consent_to_track`	Whether the donor has given permission to have their newsletter activity tracked (opens, clicks). This only applies if you are using Campaign Monitor. Added by Newsletter Connect.
`anonymous_donation`	Whether the donor chose to remain anonymous. Added by Anonymous Donations.
`donor_comment`	The comment left by the donor. Added by Donor Comments.
`giftaid`	Whether the donor claimed Gift Aid. Added by Gift Aid.
`giftaid_declaration`	The declaration the donor agreed to when they claimed Gift Aid. Added by Gift Aid.
`title`	The donor’s title (Mr, Mrs, Ms, etc.). Added by Gift Aid.
`address_3`	The third line in the donor’s address. Added by Gift Aid.

Charitable Documentation

Popular Resources