Charitable Documentation

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

Charitable Receipt Page Detection

How Automatic Receipt Page Detection Works

(Note: This is for Charitable Pro 1.8.10.5+).

When the “Donation Receipt Page” setting is set to “Automatic” in Charitable settings, the plugin automatically creates and manages receipt pages for your donations. This system works seamlessly with most WordPress themes, including both traditional (classic) themes and modern block themes.

In automatic mode, Charitable uses WordPress rewrite rules to create custom URLs like /donation-receipt/1234/ that display the receipt content without requiring you to create a physical page. The plugin handles all the technical details behind the scenes.

Themes That Work with Automatic Mode

At the time of writing (version 1.8.10.5), the following themes have been tested and work correctly with automatic receipt page detection:

Block Themes (Full Site Editing)

  • Twenty Twenty-Three – WordPress default block theme
  • Twenty Twenty-Four – WordPress default block theme
  • Twenty Twenty-Five – WordPress default block theme

Classic Themes (Traditional PHP Templates)

  • Astra – Popular multipurpose theme
  • GeneratePress – Lightweight theme
  • OceanWP – Multipurpose theme

These themes work because they properly support WordPress’s standard template hierarchy and content filters, allowing Charitable to inject the receipt content at the right time in the page rendering process.

Themes That Require Fallback Page Creation

Some themes have unique rendering systems that prevent automatic receipt page detection from working properly. When Charitable detects this issue, it automatically creates a fallback page to ensure receipts still display correctly.

Twenty Twenty-Two is a block theme that uses a different template rendering approach than later WordPress default themes. When Charitable tries to display a receipt page, the theme’s template system doesn’t properly recognize the custom receipt endpoint, resulting in a blank page.

Why it needs fallback: The theme’s block template system doesn’t correctly handle custom endpoints, causing the receipt content to not render. Charitable detects this and automatically creates a physical WordPress page with the [donation_receipt] shortcode, which the theme can then display properly.

Other documented examples at the time of this writing include YITH Wonder. YITH Wonder is a premium WooCommerce-focused theme with a custom page builder system. Similar to Twenty Twenty-Two, it has rendering quirks that prevent automatic receipt detection from working.

Note: When Charitable creates a fallback page, it automatically updates your settings to use that page. If you switch to a different theme later, Charitable will restore the “Automatic” setting if the new theme works with automatic mode.

Developer Filters

Charitable provides several filters that allow developers to customize the fallback page behavior. All filters are documented below with their default values and use cases.

charitable_receipt_fallback_enabled

Default: true

Purpose: Enable or disable the entire fallback page creation system.

When to use: If you want to completely disable automatic fallback page creation, perhaps because you’re handling receipt pages through a custom solution.

// Disable fallback page creation
add_filter( 'charitable_receipt_fallback_enabled', '__return_false' );

charitable_receipt_fallback_should_activate

Default: true

Parameters:

  • $should_activate (bool) – Whether fallback should activate
  • $current_setting (string) – Current receipt page setting (‘auto’ or page ID)

Purpose: Control whether the fallback system should activate when a blank page is detected. This gives you fine-grained control over when fallback pages are created.

When to use: If you want to prevent fallback creation in specific circumstances, such as during development or for certain user roles.

// Only activate fallback for specific themes
add_filter( 'charitable_receipt_fallback_should_activate', function( $should_activate, $current_setting ) {
    $current_theme = get_stylesheet();
    // Only allow fallback for specific problematic themes
    if ( ! in_array( $current_theme, array( 'twentytwentytwo', 'yith-wonder' ) ) ) {
        return false;
    }
    return $should_activate;
}, 10, 2 );

charitable_receipt_fallback_page_slug

Default: 'donation-receipt-page'

Purpose: Customize the URL slug for the fallback page that gets created.

When to use: If you want the fallback page to have a different URL structure, or if you need to match your site’s URL naming conventions.

// Use a custom slug for the fallback page
add_filter( 'charitable_receipt_fallback_page_slug', function( $slug ) {
    return 'receipt';
} );

charitable_receipt_fallback_page_args

Default:

array(
    'post_title'   => __( 'Donation Receipt', 'charitable-pro' ),
    'post_content' => '[donation_receipt]',
    'post_status'  => 'publish',
    'post_type'    => 'page',
    'post_name'    => $page_slug, // Set automatically
)

Purpose: Customize the properties of the fallback page when it’s created. This includes the page title, content, status, and other WordPress post properties.

When to use: If you want to customize the page title, add custom content before/after the shortcode, set a specific page template, or modify any other page properties.

// Customize the fallback page
add_filter( 'charitable_receipt_fallback_page_args', function( $args ) {
    // Change the page title
    $args['post_title'] = 'Your Donation Receipt';
    
    // Add content before the shortcode
    $args['post_content'] = '<p>Thank you for your donation!</p>' . "\n" . '[donation_receipt]';
    
    // Set a custom page template (if your theme supports it)
    // $args['page_template'] = 'custom-receipt-template.php';
    
    return $args;
} );

charitable_receipt_fallback_delete_on_theme_switch

Default: false

Purpose: Control whether the fallback page should be automatically deleted when switching away from a problematic theme.

When to use: If you want to clean up fallback pages automatically when they’re no longer needed. By default, pages are kept (but settings are restored to “Automatic”) so you can manually review or delete them.

// Automatically delete fallback page on theme switch
add_filter( 'charitable_receipt_fallback_delete_on_theme_switch', '__return_true' );

Debugging

If you need to debug receipt page issues, you can enable detailed logging by adding this to your wp-config.php file:

define( 'CHARITABLE_DEBUG_RECEIPT_PAGE', true );

This will log critical events like fallback activation, page creation failures, and theme switch handling to your WordPress debug log (requires WP_DEBUG_LOG to be enabled).

Summary

The automatic receipt page system works seamlessly with most WordPress themes. When a theme has rendering issues that prevent automatic detection, Charitable automatically creates a fallback page to ensure receipts always display correctly. Developers can customize this behavior using the provided filters, and the system automatically restores settings when switching themes.

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!

Donations New

👥 Introducing Donor Merging: Two Records, One Supporter!

Somewhere in your donor list is a supporter who appears twice, because they gave from a work address one year and a personal one the next. Every donation is still recorded and every receipt still went out, but a loyal supporter who has given for years can look like two people who gave half as much. From the Charitable Pro plugin 1.8.19.1 you can find those records and merge them from the Donors screen. Why this is important:

  • 🔍 A Find Duplicates link where you already work: Head to Charitable » Donors and it sits next to Filter and Export, then tells you how many groups of possible duplicates it found.
  • 🧩 Grouped by name, not by email: Charitable compares the first and last name together and ignores capital letters, spacing and punctuation, which is what catches the same person under two different addresses.
  • 📊 A preview before anything changes: Each group shows every record with its email address, its donation count and its lifetime total, and the preview shows you the combined totals and the email that will be added.
  • ↩️ Every merge can be undone: Nothing is merged until you choose to merge it, and you can reverse any merge afterwards, so a wrong guess costs you nothing.
  • 📥 Built for the week after an import: Moving donors over from another plugin is where most duplicates come from, and it is also when they are hardest to spot, because every record is new to you.

Check out our announcement here.

ambassadors New

🔑 Introducing Passwordless Fundraisers: Sign Up With Just an Email!

Supporters arrive wanting to help, and then the form asks them to invent a password for a website they may only visit twice. A lot of them stop right there. Passwordless Fundraiser Accounts, new in Charitable Ambassadors 3.5.0, let a supporter start a peer to peer fundraiser with nothing but an email address. Why this is important:

  • 🔑 No password step to lose them at: Switch it on in Charitable » Ambassadors » Templates » Submit Form and the create-fundraiser form asks only for a name, an email address and a page title.
  • 👤 Still a real WordPress account: One click in one email confirms the address, signs them in and creates the account, so they can come back later to edit their story, change their photo and see who has donated.
  • 🎚️ Your call on every campaign: Each peer to peer campaign can follow the site default or override it, which matters when a campaign pays fundraisers through Stripe Connect and those people do need a password.
  • 📋 See who has not clicked yet: The Charitable » Ambassadors » Directory » Awaiting Sign-In tab lists everyone still waiting, with the campaign they joined and a Resend button, so a typo or a spam folder is something you can spot and fix.
  • 🛡️ Links a scanner cannot use up: Opening the link only shows a page, and your fundraiser is signed in when they press the button on it, so corporate email scanners never burn the link. Each one works once, expires on its own and is stored only as a hash.

Check out our announcement here.

ambassadors New

🏃 Introducing Activity: Show Progress on More Than Money!

Most peer-to-peer fundraisers are about more than the money. A read-a-thon is about minutes read, a walkathon is about miles walked, and a food drive is about meals packed. Activity for Charitable Ambassadors lets your fundraisers show that effort right beside the dollars they raise. Why this is important:

  • 🎯 Progress on what you actually count: A progress bar shows each thing you count against its own target, sitting right beside the money raised.
  • 🏅 Milestones for the yes or no things: A milestone badge marks the efforts that are simply done or not done, with no number to chase.
  • ✍️ Fundraisers log their own numbers: Your supporters enter their totals from their own pages, so the effort stops living in a spreadsheet, a comment, or nowhere at all.
  • 🤖 Some numbers count themselves: An AUTOMATIC tag appears wherever the site worked the figure out from completed donations, so you can see at a glance what nobody typed in.
  • 🧩 Set it up once, use it anywhere: You decide what gets counted one time, then choose which campaigns count it. Available now in Charitable Ambassadors 3.4.7, with no new plugin and no developer.

Check out our announcement here.

ambassadors New

🖨️ Introducing Fliers and Posters: Raise Money Away From the Screen!

A lot of peer-to-peer fundraising happens away from a screen: at the finish line of a 5K, on a school noticeboard, in an office kitchen. Charitable Ambassadors 3.4.7 adds 2 printables, a fundraiser flier carrying each fundraiser’s own story and QR code, and a recruitment poster that signs new fundraisers up. Both open as a normal web page and print straight from the browser. Why this is important:

  • 🏁 A flier for every fundraiser: Each one carries that fundraiser’s own photo, story and goal, with a QR code that opens their page rather than your main campaign.
  • 📌 A poster that recruits: It shows “Now Recruiting” above your campaign name with a large QR code that opens your sign-up form, so someone can start fundraising without waiting on a link from you.
  • 🪄 No design tool needed: Both printables render as a normal web page and print from the browser, with no PDF plugin and no designer.
  • 📄 2 flier layouts: Hand out carries the full story for giving to friends and family, and Post up carries a short hook with 5 tear-off tabs for a noticeboard.
  • 🛡️ Off until you switch it on: Fliers stay off after the update until you enable them under Charitable » Ambassadors » Other » Fliers, and only the owner or an administrator can open one.

Check out our announcement here.

Improvement Payments

💸 Introducing Tiered Rates for Fee Relief: Match the Ask to the Gift!

Fee Relief asks your donors one short question at checkout: would you like to cover the processing fee on this gift? Until now that question used a single rate for every donation on a gateway, so a $10 gift and a $500 gift were asked for the same percentage. Fee Relief 1.3.0 lets you set as many donation bands as you like, each carrying its own rate. Why this is important:

  • 🪙 Gentler on small gifts: A fixed transaction cost is a far bigger share of a $10 donation than a $500 one, so bands let you ask for less at the bottom.
  • 🎚️ As many bands as you need: Each band carries its own percentage and its own fixed amount, and the top band runs on with no upper limit.
  • 🛑 An optional ceiling: A Maximum fee field stops any donor being asked for more than a number you choose, however large the gift.
  • 🔌 Set per payment gateway: Stripe can run on four bands while Windcave and Payfast stay on a single rate, because bands belong to a gateway and not to your whole site.
  • 🛡️ Nothing changes until you say so: Your current rates stay exactly as they are until you switch Use Tiered Rates on under Charitable » Settings » Advanced » Fee Relief.

Check out our announcement here.