Charitable Documentation

Learn how to make the most of Charitable with clear, step-by-step instructions.

Adding Custom Fields to PDF Receipts

Would you like a custom field from your donation form to show up on the PDF receipt? When you add a custom field to a legacy form or build one in the campaign visual builder, Charitable saves the donor’s answer with the donation – but the PDF receipt template doesn’t print it automatically. You’ll need to tell the receipt where the value lives and how to display it.

This guide will walk you through the steps to add a custom donation field to your PDF receipt, whether the field came from a legacy form or the visual form builder.

Note: This section assumes you are using Charitable Pro 1.8.13+ and involves a small amount of PHP. If you’re not comfortable editing code, paste the snippet into a tool like WPCode so you don’t have to touch theme files directly, or hand it to your developer.

How Are Custom Fields Stored?

Before you can show a field on the receipt, you need two things: where its value is stored, and what key to look it up by. Charitable saves both legacy form and visual form custom fields as donation post meta, but the meta key looks different depending on which form created it.

For legacy form custom fields, the meta key is whatever was registered with the field. If you registered a field with the key t_shirt_size using the Donation Fields API, the value is stored under that exact key.

For visual form custom fields, the key uses the format field_X, where X is the numeric ID the campaign builder assigned to the field. Hidden fields are the exception – those use whatever name you typed into the Field Name setting.

Finding the Meta Key for Your Field

The easiest way to confirm which meta key a field uses is to look at a real donation that included the field.

For a legacy form, the meta key is the array key you used when registering the field with the charitable_default_donation_fields filter. If you didn’t write the snippet yourself, you can search your site (or ask your developer) for that filter to confirm the key.

For a visual form, go to Charitable » Donations, open a test donation that submitted the custom field, and look through the donation’s saved data for entries like field_3 or field_5. The number is the field’s builder ID. If you’d rather see every meta key in one shot, you can drop this temporary snippet onto any admin page:

echo '<pre>';
print_r( get_post_meta( 123 ) ); // Replace 123 with your test donation ID.
echo '</pre>';

Note: Once you’ve copied down the keys you need, remove the snippet – leaving print_r() calls in production output is messy and can leak donor data.

Adding a Field Using a Hook (Recommended)

Charitable fires an action called charitable_pdf_receipt_after_donor_details right after the donor details block on every PDF receipt. Hooking into this action is the simplest way to add a custom field, because you don’t have to override any template files – your changes survive plugin updates with no extra work.

To activate the snippet, paste it into your child theme’s functions.php file or into a code snippets plugin:

add_action( 'charitable_pdf_receipt_after_donor_details', function( $donor, $donation ) {

    // Replace 't_shirt_size' with your field's meta key.
    // For a visual form custom field, this will look like 'field_3'.
    $value = get_post_meta( $donation->ID, 't_shirt_size', true );

    if ( empty( $value ) ) {
        return;
    }

    printf(
        '<p style="margin-top: 10px; margin-bottom: 0;"><strong>%s:</strong> %s</p>',
        esc_html__( 'T-Shirt Size', 'charitable-pro' ),
        esc_html( $value )
    );

}, 10, 2 );

The example prints the field underneath the donor’s name, address, and email. When adapting it, swap the meta key, the visible label, and the markup to match the field you’re adding.

Note: If your value contains HTML – for example, output from a long-text field – use wp_kses_post() instead of esc_html() so basic formatting tags survive.

Adding a Field by Overriding the Template

If you need to place the field somewhere other than after the donor details – for example, inside the donations table or in the footer – you can override the PDF receipt template.

Charitable’s PDF templates are theme-overridable. To customize the main PDF layout, copy this file:

wp-content/plugins/charitable-pro/templates/pro/pdf-receipts/pdf.php

Into your active theme at this path:

wp-content/themes/your-theme/charitable-pro/pro/pdf-receipts/pdf.php

Once your copy is in place, Charitable will load it instead of the plugin’s version. The same path pattern works for the two partial templates that pdf.php calls:

  • Donor details: templates/pro/pdf-receipts/donation-receipt/donor-details.php
  • Donation details: templates/pro/pdf-receipts/donation-receipt/details.php

Inside any copied template, the $donation variable is the full Charitable_Donation object. To pull a custom field’s value, use the same get_post_meta() call from the previous method, then add markup wherever you want the value to appear:

<?php
$value = get_post_meta( $donation->ID, 'field_3', true );
if ( ! empty( $value ) ) :
    ?>
    <p><strong><?php esc_html_e( 'Gift Aid Eligible', 'charitable-pro' ); ?>:</strong> <?php echo esc_html( $value ); ?></p>
    <?php
endif;
?>

Note: Template overrides need to be reviewed every time you update Charitable Pro. If the plugin’s version of the template picks up new features or bug fixes, your override won’t see them automatically. The hook method above avoids this entirely, so use a template override only when you need control over placement.

Previewing Your Changes

Once your snippet or template override is saved, generate a real PDF to confirm the field appears as expected. From the Charitable » Donations screen, pick a donation that included the custom field, then click the PDF icon next to it to download the receipt. If the field doesn’t appear, work through these checks one at a time:

  • Confirm the meta key matches exactly – field_3 and field_03 are not the same.
  • Verify the donation you’re testing actually submitted a value for the field. Empty values won’t print.
  • Try a different test donation to rule out one entry being empty.

Note: Field values that look empty on the donation admin screen will also be empty on the PDF. The receipt cannot show data the donation never collected.

Still have questions? We’re here to help!

Last Modified:

What's New In Charitable

View The Latest Updates
🔔 Subscribe to get our latest updates
📧 Subscribe to Emails

Email Subscription

Join our Newsletter

We won’t spam you. We only send an email when we think it will genuinely help you. Unsubscribe at any time!

Improvement Payments

💳 New Braintree Features For Your European Donors

If your nonprofit serves international supporters, credit cards aren’t always their preferred way to give. With the release of the Braintree addon version 1.3.0, you can now empower your European donors with the payment methods they trust most.

What’s New:

🌍 Six New European Payment Methods: Seamlessly accept popular bank-based options like iDEAL (Netherlands), Bancontact (Belgium), BLIK (Poland), EPS (Austria), Przelewy24 (Poland), and MyBank (Italy/Portugal).

⚡ Frictionless Donor Experience: No manual card entries required. Donors safely authenticate directly with their own bank in a secure popup for lightning-fast contributions.

⚙️ Automatic Currency Sync: Skip complex configuration. The addon intelligently displays the correct local payment buttons based automatically on your site’s currency (EUR or PLN).

Ready to scale your global reach? Update to Braintree 1.3.0 today!

Campaigns New

⏳ Campaign Countdown: Drive Urgency and Lift Donations

Urgency is one of the most powerful tools in fundraising! Meet Campaign Countdown—a live, real-time timer built to turn procrastination into immediate generosity.

campaign_countdown_animation

What’s New:

⏱️ Live, Real-Time Urgency: Beautifully track days, hours, minutes, and seconds down to your campaign’s deadline w/ live-updating visual countdowns.

🎨 Tailored to Your Look: Choose between Boxed bordered tiles or a clean, single-line Inline display. Match your theme instantly with font and deep color controls.

🛠️ Place it Anywhere: Drop the countdown anywhere you like using the Campaign Builder field, a dedicated Gutenberg block, or a simple shortcode.

🚨 Smart Expiry Actions: Total control over the end state—choose to automatically replace the timer with a custom message, freeze it at zero, and more.

Improvement Migrations

↔️ Importing From GiveWP, Donorbox, GiveButter… even CSV!

Whether you’re migrating from another platform or consolidating your records, moving your data to Charitable is now faster and more flexible than ever. We’ve streamlined the process so you can bring over your entire fundraising history in just a few clicks.

🔄 Native GiveWP, Donorbox, & GiveButter Support: Switching from a major platform? Our dedicated migration tools handle the heavy lifting, automatically mapping your donors and donations directly into Charitable—no technical skills required.

📂 Universal CSV Import: Moving from a custom system or a specialized CRM? If you can export it to a CSV, you can import it here. Our smart mapping tool lets you align your columns to Charitable fields like names, emails, phone numbers, and addresses in seconds.

Instant Donor Profiles & Custom Tags: Automatically create rich donor profiles and bring in custom tags to keep your data organized. Segment and engage your supporters from day one with a clean, professional database structure.


Ready to make the switch?

Check out our GiveWP Migration Guide

Learn more about our Import Tools

Improvement Payments

💳 New Braintree Features For Your European Donors

With the release of Braintree addon version 1.3.0, you can now empower your European donors with the payment methods they trust and prefer, making giving seamless for international supporters.

🌍 Six New European Payment Methods: Support popular local options like iDEAL (Netherlands), Bancontact (Belgium), BLIK (Poland), and more to meet donors where they are.

⚡ Frictionless Donor Experience: These bank-based methods allow donors to authenticate directly with their own bank in a secure popup… no credit card numbers required.

⚙️ Automatic Currency Sync: No complex setup needed. The builder automatically displays the correct payment buttons based on your site’s currency (EUR or PLN), ensuring a relevant experience for every visitor.

Campaigns New

🖼️ Campaign Featured Images: Pro-Level Visuals Made Simple

With the new Campaign Featured Image setting in our visual builder, you now have a single, dedicated place to manage how your fundraisers look across your entire site and beyond.

🖼️ One Image, Everywhere: Set a primary thumbnail that automatically syncs to campaign grids, lists, and shortcodes—no more relying on layout order.

📱 Social Sharing Optimized: Easily upload images at the perfect size to ensure your campaigns look stunning and professional when shared on social media.

🔍 SEO & Accessibility Ready: Add custom alt text directly within the builder to improve search rankings and ensure your mission is accessible to every supporter.