Charitable Documentation

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

Hooks and filters in Ambassadors

Please note: This documentation is a work in progress and does not yet cover all filters & action hooks available in Charitable Ambassadors. If you do not see a hook or filter describing what you need to do, please get in touch via our support page and we can help you.

Filters

charitable_ambassadors_fundraiser_title

Added in version 2.0.0

u003cpu003eChange the automatically generated title for a new fundraiser, when the title is set to be dynamically based on the campaign creator’s name.u003c/pu003e

Return Value

u003cpu003eString. The title of the fundraiser.u003c/pu003e

Arguments

  • $title (string)

    u003cpu003eThe title. By default this will be the campaign creator’s full name.u003c/pu003e

  • $data (array)

    u003cpu003eThe submitted data.u003c/pu003e

Usage

add_filter( 'charitable_ambassadors_fundraiser_title', function( $title, $data ) {n    $first_name = array_key_exists( 'first_name', $data ) ? $data['first_name'] : '';n    $last_name  = array_key_exists( 'last_name', $data ) ? $data['last_name'] : '';n    $full_name   = trim( sprintf( '%s %s', $first_name, $last_name ) );nn    // Joe Blow's Fundraisern    return sprintf( u0022%s's Fundraiseru0022, $full_name );n}, 10, 2 );

Added in version 2.0.0

u003cpu003eChoose whether you want to show the u0022Create a New Campaignu0022 button at the bottom of the output of the [charitable_my_campaigns] shortcode.u003c/pu003e

Return Value

u003cpu003eBoolean. True if you do want to show it, or false if you would prefer not to. This will return true by default.u003c/pu003e

Arguments

  • $show (boolean)

    u003cpu003eWhether to show the button.u003c/pu003e

Usage

// Do not show the button.nadd_filter( 'charitable_ambassadors_my_campaigns_show_campaign_creation_link', '__return_false' );

charitable_ambassadors_my_campaigns_button_text

Added in version 1.0.0

u003cpu003eChange the text of the u0022Create a Campaignu0022 button at the bottom of the [charitable_my_campaigns] shortcode.u003c/pu003e

Return Value

u003cpu003eString. The text to use in the button.u003c/pu003e

Arguments

  • $text (string)

    u003cpu003eThe button text.u003c/pu003e

Usage

add_filter( 'charitable_ambassadors_my_campaigns_button_text', function( $text ) {n    return 'Start a New Campaign';n} );

Added in version 1.0.0

u003cpu003eChange the page that users will be redirected to after they submit their campaign for the first time. Note that if you want to redirect to a static page, you can do this without code by configuring the u0022Campaign Submission Success Pageu0022 setting under Charitable u003e Settings u003e Ambassadors.u003c/pu003e

Return Value

u003cpu003eString. A URL to redirect to after first submitting a campaign. Note that the redirect is done through a call to u003ccodeu003ewp_safe_redirect()u003c/codeu003e, so the URL should be to an allowed host (see u003ca href=u0022https://developer.wordpress.org/reference/functions/wp_safe_redirect/u0022u003ehttps://developer.wordpress.org/reference/functions/wp_safe_redirect/u003c/au003e).u003c/pu003e

Arguments

  • $default (string)

    u003cpu003eThe URL to redirect to.u003c/pu003e

  • $args (array)

    u003cpu003eAn array of arguments. By default, this will only have a u003ccodeu003ecampaign_idu003c/codeu003e property with the ID of the newly submitted campaign.u003c/pu003e

Usage

// Redirect to the newly submitted campaign after submission.nadd_filter( 'charitable_permalink_campaign_submission_success_page', function( $url, $args = array() ) {n    if ( ! array_key_exists( 'campaign_id', $args ) ) {n        return $url;n    }nn    return get_permalink( $args['campaign_id'] );n}, 10, 2 );

charitable_campaign_submission_redirect_url

Added in version 1.0.0

u003cpu003eChange the URL that users are redirected to after they submit, update or save u0026amp; preview their campaign.u003c/pu003eu003cpu003eIf you only want to change the page that users are redirected to after they first submit their campaign, use the u003ca href=u0022https://www.wpcharitable.com/documentation/hooks-filters-in-ambassadors/#charitable_permalink_campaign_submission_success_pageu0022u003echaritable_permalink_campaign_submission_success_pageu003c/au003e filter instead.u003c/pu003e

Return Value

u003cpu003eString. The URL that the user will be redirected to.u003c/pu003e

Arguments

  • $url (string)

    u003cpu003eThe URL that the user will be redirected to.u003c/pu003e

  • $data (array)

    u003cpu003eThe submitted data.u003c/pu003e

  • $campaign_id (int)

    u003cpu003eThe campaign ID.u003c/pu003e

  • $user_id (int)

    u003cpu003eThe user ID.u003c/pu003e

charitable_ambassadors_fundraiser_form_field_list

Added in version 2.1.0

u003cpu003eAdd or remove fields to the fundraiser form. u003c/pu003eu003cpu003eThe fields list is a list of keys of fields that are included in the main campaign form, which should also be included in the fundraiser form. The following fields are not included in the fundraiser form by default:u003c/pu003eu003cpu003e- u003ccodeu003edescriptionu003c/codeu003eu003cbru003e- u003ccodeu003ecategoriesu003c/codeu003eu003cbru003e- u003ccodeu003etagsu003c/codeu003eu003cbru003e- u003ccodeu003esuggested_donationsu003c/codeu003eu003cbru003e- u003ccodeu003eallow_custom_donationsu003c/codeu003eu003c/pu003e

Return Value

u003cpu003earrayu003c/pu003e

Arguments

  • $list (array)

    u003cpu003eThe list of fields to be included.u003c/pu003e

  • $form (Charitable_Ambassadors_Fundraiser_Form)

    u003cpu003eThe fundraiser form object.u003c/pu003e

Usage

// Include the 'description' field in the Fundraiser form.nadd_filter( 'charitable_ambassadors_fundraiser_form_field_list', function( $fields ) {n    $fields[] = 'description';n    return $fields;n} );

charitable_ambassadors_fundraiser_inherited_fields

Added in version 2.0.0

u003cpu003eFilter the fields that are automatically inherited from the fundraiser’s parent campaign.u003c/pu003e

Return Value

u003cpu003earrayu003c/pu003e

Arguments

  • $fields (array)

    u003cpu003eThe inherited fields.u003c/pu003e

Usage

add_filter(n    'charitable_ambassadors_fundraiser_inherited_fields', n    function( $fields ) {n        $fields[] = 'my_custom_field';n        return $fields;n    }n);

charitable_ambassadors_update_fundraiser_end_dates_on_parent_end_date_change

Added in version 2.0.0

u003cpu003eSet whether end dates of fundraisers should be updated automatically when a parent campaign has its end date changed.u003c/pu003e

Return Value

u003cpu003eBoolean. Defaults to true.u003c/pu003e

Arguments

  • $should_update (boolean)

    u003cpu003eWhether to update automatically.u003c/pu003e

  • $campaign (Charitable_Campaign)

    u003cpu003eThe parent campaign object.u003c/pu003e

charitable_ambassadors_creator_donations_export_columns

Added in version 2.0.0

u003cpu003eFilter the columns that are included in the export.u003c/pu003e

Return Value

u003cpu003eArray. The keys of columns to include.u003c/pu003e

Arguments

  • $columns (array)

    u003cpu003eThe columns to include.u003c/pu003e

Usage

add_filter( 'charitable_ambassadors_creator_donations_export_columns', function( $columns ) {n    // Only show the first name, last name, amount and donor comment.n    $included_columns = array(n        'first_name',n        'last_name',n        'amount',n        'donor_comment',n    );ntn    foreach ( $columns as $column =u003e $header ) {n        if ( ! in_array( $column, $included_columns ) ) {n            unset( $columns[ $column ] );n        }n    }ntn    return $columns;n} );

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.