Charitable Documentation

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

Popular Resources

Start Here

Donor Management

Recurring Donations

Peer-to-Peer Fundraising

Integrations

Extensions

How to Use Conversion Tracking in Charitable

Conversion Tracking sends native Meta Pixel, TikTok Pixel, and Google Tag Manager dataLayer events from your campaign pages, donation forms, and receipt pages. Every event carries full donation context, including amount, currency, campaign name, donation type, and payment method, so your ad platforms can optimize spend based on real fundraising outcomes.

Available with Charitable Pro 1.8.13.5+ or later on Pro, Agency, and Elite license plans.

Key Features

  • Fire Meta Pixel Purchase and Donate events on every confirmed donation
  • Fire TikTok Pixel CompletePayment events with full donation value and currency
  • Push rich donation data to window.dataLayer for Google Tag Manager and GA4
  • Track campaign page views and donation form opens as top-of-funnel events
  • Include donation amount, currency, campaign name, donation type, and payment method in every conversion
  • Respect visitor consent via the WP Consent API, with a filter hook for custom consent managers
  • Prevent duplicate conversions on receipt page refreshes using tab-scoped session tracking
  • Review tracking status for every donation inside the WordPress admin

Why Use Conversion Tracking?

Nonprofits running paid ads on Meta, TikTok, or through Google Tag Manager need accurate conversion attribution to optimize ad spend and prove ROI. Generic pixel plugins fire empty events that only tell the ad platform a “conversion” happened. Charitable Conversion Tracking sends the donation amount, currency, and campaign context that Meta and TikTok algorithms actually use to find more donors who will give. Your acquisition cost per donor drops. Your campaigns learn faster.

Requirements

  • Charitable Pro 1.8.13 or later
  • A Charitable Pro, Agency, or Elite license plan
  • WordPress 5.0 or later
  • PHP 7.2 or later
  • Optional: WP Consent API and a compatible consent management plugin, if you want pixels gated by visitor consent

Getting Started

Activation

  1. Download the Conversion Tracking addon from your Charitable account dashboard.
  2. In WordPress, go to Plugins > Add New > Upload Plugin and upload the ZIP file.
  3. Activate Charitable – Conversion Tracking.
  4. Go to Charitable > Settings > Advanced > Conversion Tracking to enter your pixel IDs.

Enter Your Pixel IDs

Each platform has a single ID field. Leaving a field empty disables that platform. No separate on/off toggle is needed.

Usage

Conversion Tracking runs automatically once pixel IDs are entered. There is no block or shortcode to place. The addon listens on three moments across your site:

  • Campaign page view. Fires when a visitor loads a single campaign page.
  • Donation form rendered. Fires when a donation form is displayed on any page.
  • Donation confirmed. Fires on the receipt page after a successful donation, for all gateways including Stripe, PayPal, Square, Braintree, Mollie, and Offline.

Configuration Options

Platform IDs

ParameterTypeDefaultDescription
meta_pixel_idstringemptyYour 15-digit Meta Pixel ID. Example: 123456789012345
tiktok_pixel_idstringemptyYour TikTok Pixel ID. Example: CXXXXXXXXXXXXXXX
gtm_container_idstringemptyYour GTM Container ID. Charitable pushes dataLayer events but does not load GTM itself. Install GTM through your theme or a separate plugin. Example: GTM-XXXXXXX

Tracking Behavior

ParameterTypeDefaultDescription
pixel_track_campaign_viewscheckboxonFire ViewContent and charitable_campaign_viewevents when a visitor loads a campaign page
pixel_track_form_openscheckboxonFire InitiateCheckout and charitable_initiate_checkout events when a donation form is rendered
pixel_consent_integrationcheckboxonCheck wp_has_consent( 'marketing' ) before firing any pixel

Event Reference

MomentMeta PixelTikTok PixelGTM dataLayer Event
Campaign page viewViewContentViewContentcharitable_campaign_view
Donation form renderedInitiateCheckoutInitiateCheckoutcharitable_initiate_checkout
Donation confirmedPurchase and DonateCompletePaymentcharitable_donation_complete

dataLayer Payload on Donation Complete

window.dataLayer.push({
  event: 'charitable_donation_complete',
  donationId: 8937,
  value: 28.87,
  currency: 'USD',
  campaignId: 7952,
  campaignName: 'Clean Water for Rural Communities',
  donationType: 'one-time',
  paymentMethod: 'stripe'
});

Customization

Multiple Campaigns in One Donation

When a donation covers more than one campaign, Conversion Tracking uses the campaign with the largest donation amount as the attribution target. The total value is the sum across all campaigns. Use the charitable_pixel_primary_campaign filter to override this selection.

Donation Statuses That Fire Conversions

By default, Conversion Tracking fires pixels for donations with charitable-completed, charitable-preapproved, and charitable-pending statuses. Use the charitable_pixel_fire_statuses filter to add or remove statuses.

Troubleshooting

No pixel events appear in Meta Events Manager or TikTok Events Manager

Check that the pixel ID field is populated for that platform and that your visitor has granted marketing consent (or that pixel_consent_integration is disabled). Open your browser DevTools Network tab on the receipt page and filter for fbevents.js or analytics.tiktok.com to confirm the pixel library loads.

GTM dataLayer events fire but GTM tags do not

Charitable pushes events to window.dataLayer but does not install the GTM container itself. Install GTM through your theme header or a dedicated GTM plugin. Confirm the container ID in GTM matches the ID entered in Conversion Tracking settings.

Receipt page events do not fire

Check the donation status. Offline donations that sit in charitable-pending without being manually approved will not fire pixels. Also confirm the donation passed through the receipt page rather than a custom thank-you redirect, since Conversion Tracking relies on the charitable_donation_receipt_page hook.

Conversion tracked twice when visitor refreshes receipt page

Conversion Tracking uses sessionStorage keyed by donation ID to prevent re-firing in the same browser tab. Opening the receipt URL in a new tab counts as a new session and will fire once, which is the expected behavior.

License inactive banner appears in admin

Confirm Charitable Pro is installed and activated, your license is on the Pro, Agency, or Elite plan, and the license has been entered and activated in Charitable > Settings > Licenses. Expired licenses have a 30-day grace period before delivery is blocked.

Developer Resources

Hooks and Filters

  • charitable_pixel_fire_statuses — array of donation statuses that allow pixels to fire
  • charitable_pixel_primary_campaign — override the campaign chosen for multi-campaign donations
  • charitable_pixel_consent_granted — fallback consent check when WP Consent API is unavailable
  • charitable_ajax_donation_response — added to Charitable Pro core; lets addons enrich the AJAX donation response for future Conversions API work

Donation Meta Keys

  • _charitable_pixel_tracking_status — tracked, consent_blocked, status_blocked, license_blocked, or not_configured
  • _charitable_pixel_tracked_at — Unix timestamp of the tracking event
  • _charitable_pixel_platforms — array of platforms that fired, e.g., ['meta', 'tiktok', 'gtm']
  • _charitable_pixel_event_id — unique event ID reserved for future Meta Conversions API deduplication

Consent Integration

Conversion Tracking reads consent through the WP Consent API when available:

if ( function_exists( 'wp_has_consent' ) ) {
    return (bool) wp_has_consent( 'marketing' );
}
return (bool) apply_filters( 'charitable_pixel_consent_granted', true, 'marketing' );

Sites without a consent manager fire pixels by default. Sites with a compatible consent plugin (CookieYes, Complianz, and others that implement the WP Consent API) have consent respected automatically.

Additional Resources

Still have questions? We’re here to help!

Submit a Support Ticket
Contact Us

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

💸 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.

Donations Improvement

📊 Your Pro Dashboard Can Now Compare, Export, and Score!

Most fundraising dashboards only tell you how much you have raised. Charitable Pro 1.8.19 rebuilds the dashboard and the Reports Overview around the harder questions: whether anything is broken, whether this period beat the last one, and which single change would make the most difference today. Why this is important:

  • 📈 Every figure has a trend: Pick a period and the tiles and the chart move together, with each total shown against the previous period.
  • 🗓️ Charts that stay readable: Short ranges group donations day by day, while longer ranges group by week or month, so a full year reads as a curve instead of a flat line.
  • 🔀 Compare any 2 periods: Not just consecutive ones, so you can ask how this December did against last December. That matters because fundraising is seasonal.
  • 📤 Export the whole summary: Send the full overview out as CSV or PDF, ready for a board pack or a funder report.
  • 🎯 Score your setup for free: Have your fundraising setup scored, so the one change worth making next is the one you can see.

Check out our announcement here.

Feature New

🎟️ Introducing Charitable Events: Sell Tickets Inside Your Campaigns!

Most nonprofits sell event tickets in one tool and collect donations in another, which leaves two sets of reports and a manual match at the end of the year. Charitable Events brings both together, selling tickets through the same donation forms and payment gateways you already run in Charitable. Why this is important:

  • 🎟️ Every ticket is a donation: Ticket sales run through the gateway you already use and count toward the campaign goal, with everything managed under Charitable » Events.
  • 📱 QR check-in from any phone: Each attendee gets their own QR code on the receipt, and volunteers scan at the door through a check-in link that needs no WordPress account.
  • 🧾 Receipts ready for tax time: Give each ticket type a fair market value, and Charitable puts the correct tax-deductible amount on every donor receipt.
  • 📋 Attendee details at checkout: Ask every guest for a meal choice, shirt size, or access needs, with a separate attendee record created for each ticket.
  • 🗓️ Blocks and calendars included: Three editor blocks plus Sugar Calendar and The Events Calendar support put your events where supporters already look.

Check out our announcement here.

ai New

🚀 Unleash AI Power in Charitable!

Your AI assistant can now build, edit, and manage your Charitable fundraising campaigns directly — just by asking. With Charitable Pro adding write support for the WordPress Abilities API, tools like ChatGPT, Claude, and Cursor can handle full administrative actions safely through MCP. Why this is important:

  • 🤖 Campaign creation in plain language: Prompt your assistant with a goal like “Set up a fundraiser for the shelter with a $5,000 goal”, and it builds a real draft campaign complete with suggested donation tiers.
  • 🎨 Instant donation form tweaks: Add custom fields, change button colors, or reorder elements without diving into form settings.
  • 📝 Offline gift logging: Tell your assistant about cash or check gifts, and it will match donor emails and record transactions into your history.
  • 🛡️ Safety and control by default: Write access stays strictly off until turned on in Charitable » Tools » AI MCP, keeping read-only reporting safe by default.
  • 📜 Full audit logging: Every change made by an AI assistant is tracked under Charitable » Tools » Logs, so you always know who (or what) updated your site.

Check out our announcement here.

Improvement Payments

💰 Accept Recurring Donations with Windcave and Charitable

A donor sets their gift up once on Windcave’s secure payment page, and Charitable bills every renewal after that on schedule. Why this is important:

🏦 Organizations banked in New Zealand or Australia: monthly giving on the gateway your bank already set you up with, with no second processor to onboard.
⛪ Churches taking regular tithes and offerings: congregants set their own schedule once, which is the simplest way to launch recurring church giving without a separate platform.
🌏 Groups with donors in several currencies: Windcave handles more than 20, so a supporter can give in the currency they actually hold.
📅 Operating funds rather than one-time campaigns: switch on Recurring Only mode and the one-off option disappears, so every gift to that campaign is a subscription.
🧾 Teams with no developer on staff: 3 sets of credentials pasted into a settings page, and no code anywhere.

Check out our announcement here.

View All Announcements