Skip to content

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 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?

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:

Full list of default donation fields

The following fields are added by Charitable and its extensions:

KeyDescription
donation_idThe donation ID
first_nameThe donor’s first name.
last_nameThe donor’s last name.
donorThe donor’s full name.
emailThe donor’s email address.
donor_addressThe donor’s full address, formatted.
addressThe donor’s first address field.
address_2The donor’s second address field.
cityThe donor’s city.
stateThe donor’s state.
postcodeThe donor’s postcode.
countryThe donor’s country.
phoneThe donor’s phone number.
campaignsThe campaign that received the donation.
campaign_categories_listThe categories that the campaign is in.
amount_formattedThe donation amount, formatted according to your currency settings.
dateThe date of the donation.
timeThe time the donation was made.
statusThe donation status. This returns the raw value of post_status.
status_labelThe donation status as a more readable label.
donation_gatewayThe payment gateway used for the donation.
gateway_labelThe payment gateway as a reader-friendly string.
donation_keyThe unique donation key.
gateway_transaction_idThe transaction ID for the donation in the payment gateway that was used (i.e. PayPal, Stripe).
test_modeWhether the donation was made in test mode.
donation_summaryA readable summary of the donation, listing the campaign receiving the donation & the amount donated.
contact_consentWhether the donor gave their consent to be contacted.
cover_feesWhether the donor covered fees.
Added by Fee Relief.
fee_amountThe amount of processing fees paid by the donor.
Added by Fee Relief.
fee_amount_formattedThe amount of processing fees paid by the donor, formatted according to your currency settings.
Added by Fee Relief.
total_donation_with_feesThe total donation amount including processing fees.
Added by Fee Relief.
total_donation_with_fees_formattedThe total donation amount including processing fees, formatted according to your currency settings.
Added by Fee Relief.
consent_to_trackWhether 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_donationWhether the donor chose to remain anonymous.
Added by Anonymous Donations.
donor_commentThe comment left by the donor.
Added by Donor Comments.
giftaidWhether the donor claimed Gift Aid.
Added by Gift Aid.
giftaid_declarationThe declaration the donor agreed to when they claimed Gift Aid.
Added by Gift Aid.
titleThe donor’s title (Mr, Mrs, Ms, etc.).
Added by Gift Aid.
address_3The third line in the donor’s address.
Added by Gift Aid.