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: wahr
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: wahr
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.
