Tips For Writing Custom Code For Charitable

One reason Charitable is one of the best WordPress plugins to run campaigns and accept donations is it’s flexibility and ability to allow others to customize various key aspects of the experience – including emails, campaign details, and the donation form. Some of this flexibility exists in the “hooks and filters” that Charitable has in it’s code that are available to WordPress developers. Through these, a developer can customize a site to:

— Display a custom field on the donation field via the Donations Field API.
— Add new email tags or modify existing ones with the Email Fields API.
— Customizations to addons such as the Ambassador addon and the Annual Receipts addon.

Code for a WordPress plugin can be written in a number of ways and in different places: some code can be placed in the “functions.php” file of the active WordPress theme, some are written into a plugin (that can be activated and deactivated even if the user keeps the same theme), and (what is becoming increasing popular) code can be hosted in a code snippets plugin.

No matter where the code lives, there are best practices that WordPress developers and coders should be using to ensure the website it’s running in stays secure and doesn’t fall to errors. The following isn’t a complete nor in depth guide, but general reminders for those writing code OR accepting code from developers to insert into their website – especially if that code relies on a third party plugin (like Charitable). 

Plugin File Preferred

If possible try to place custom code in it’s OWN WordPress plugin. This makes it easier to keep the code in place if you switch your WordPress theme and it also allows you to easily turn the plugin containing the customizations on/off for debugging purposes. There are many posts and tutorials on the web about creating a simple WordPress plugin such as this one.

Don’t Assume, Always Check

It’s important for any custom code NOT TO ASSUME CHARITABLE IS ACTIVATED AND RUNNING ON YOUR WEBSITE. Why? Because if it attempts to call a function in Charitable’s core code – and the code isn’t there – an error can occur… an error that could bring down your website! Sometimes WordPress is able to put your site in “Recovery Mode” and send the site administrator an email to notify them about this error, but this isn’t always the case. Therefore, ANY code written for Charitable – regardless of it’s purpose or where the code is located – should “check” to make sure Charitable is activated and/or the function they are attempting to call exists.

Notice our first (bad!) example:

👎🏻 BAD EXAMPLE:

// Bad Example :-( Of Hooking Into Charitable

function charitable_add_donation_gateway_email_tag() {
    charitable()->donation_fields()->get_field( 'gateway_label' )->email_tag = true;
}
add_action( 'init', 'charitable_add_donation_gateway_email_tag' );

The purpose of this block of code is to make the “gateway label” something that can be added as a dynamic tag into Charitable emails. The developer above is “hooking” the function that does this WordPress’s “init” which is run every time a page is loaded on the website – no matter if it’s in the admin or the front end. Notice the function uses “charitable()”… but if this doesn’t exist PHP will throw a “fatal error” – and since the above code is loading on ANY and EVERY page load, the entire site will most likely crash without ability to log in as an admin, etc.

Again, it’s a good practice to never assume a function exists if that function is part of a plugin or theme (in other words if it’s not a part of WordPress core). Assuming the “charitable()” class exists means assuming the Charitable plugin will ALWAYS be there – but if the plugin is deactivated (by a human or by another plugin) or if the plugin is being updated… the function will not be found, and a (possible “fatal”) error would be encountered. Here’s the same function but with a simple addition:

👍🏻 GOOD EXAMPLE:

// Good Example :-) Of Hooking Into Charitable
// Checking To See If The Class Exists!

function charitable_add_donation_gateway_email_tag() {
    if ( class_exists('charitable') ) : // check for class
       charitable()->donation_fields()->get_field( 'gateway_label' )->email_tag = true;
    endif;
}
add_action( 'init', 'mysite_charitable_add_donation_gateway_email_tag' );

Notice the “if” statement that checks if the class of “charitable” exists – this is a way in PHP to safely check if the class exists (in this case it will only if Charitable is actively running on the website). If it doesn’t exist, then the code isn’t run and everyone is safe. It’s common for PHP developers to make checks like class_exists and function_exists for quick ways to ensure the code they are about to run won’t run into serious errors because something they are assuming exists doesn’t exist.

Use Unique Names For Functions

As noted in the above examples, never give your functions generic names like “update_email” because if another plugin uses that same name (current plugins or future ones you might install) then your website might suffer problems. When creating a function always start with “mywebsite_charitable_” (like the example above, replacing “mywebsite” with a reasonable length string of your website name) to ensure that you have likely created a custom name that isn’t repeated (you can also use the same “does this already exist logic” in the above step if you want to go the extra mile).

Enable WordPress Debugging and Debug Logs

For anything beyond a simple script, WordPress developers commonly like to document and log PHP warnings and errors to “catch” problems (especially if they aren’t apparently visible on the website). Charitable Support team recommends the base WP_DEBUG and WP_DEBUG_LOG functions as mentioned here in the WordPress documentation.

Using A Code Snippet Plugin?

Everything said above is applicable also to code inserted into code snippet plugins. If you have a problem with Charitable and know you are running custom code in a code snippet, you should be able to deactivate the code snippet plugin to see if this resolves the issue or helps you further troubleshoot.

Don’t Test On Production

Finally, it’s a good idea to test custom code on a staging or development environment and not live on your website. If you deactivate Charitable here as a test it’s a good “final” way to determine if your website might experience significant problems. This keeps your production environment safe and still able to accept donations. 


Remember that if you are unsure about the code you are adding to your theme, your own plugin, or code snippet plugin – consult with a developer. If you have some general questions feel free to reach out to our support team who will be happy to answer questions about any code you might be adding to your website to extend Charitable. We are here for you and to support you in extending your website to meet your needs!

We hope sharing these suggestions will give you the confidence and ensure your customizations to Charitable will continue to operate well for years to come.

Get free tips and resources right in your inbox, along with 60,000+ others

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!

Featured Video:

Watch more videos on our YouTube channel.

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!

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.

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.