Skip to main content

React to a completed donation — log it, send a follow-up, or update a list

Free Intermediate

When a listener completes a donation, you probably want to do something with that — log it to a CRM, add the donor to an email list, push a Slack notification, or trigger a custom thank-you sequence. This recipe shows where to hook in.

benecaster_donation_received fires after Stripe confirms payment and carries the real transaction amount, currency, and full payment details. This is the right hook for anything financial — logging, receipts, analytics. If you also support link-mode donations (where listeners pay via a direct payment link rather than the embedded widget), benecaster_listener_support_donation_logged covers both modes in one callback.

You can also add markup directly to the donation widget: benecaster_before_donation_form fires just before the widget renders (useful for legal copy or a short message), and benecaster_after_donation_confirmation fires inside the confirmation panel that appears after a successful payment (useful for a next-step link or social share prompt).

Key Patterns

Getting the full record. The logged action passes only the donation, show and user IDs — not the amount, currency, platform, reference or note. There is no public accessor for fetching the rest, so if your integration needs those values, hook benecaster_donation_received instead: it carries the full transaction and fires only for payments Stripe has confirmed. Use the logged action for the two things it is good for — knowing that something was submitted, and for which show.

Handling anonymous submissions. $user_id is null for submissions made by visitors who weren’t logged in. Check it before using it in any per-user context — passing null to get_userdata() won’t give you what you expect.

Offloading slow work. The action runs synchronously inside the REST callback, so anything slow — an HTTP call to a CRM, a query against an external system — delays the response to the listener’s browser. Hand the work to Action Scheduler and return immediately.

Notes

Fires after the row is committed. benecaster_listener_support_donation_logged runs after the row is successfully written and — when an email address was provided — the donation_thank_you email is queued. The donation is already committed; do not use this action to conditionally prevent recording.

Platform slugs are free-form strings — there is no fixed list. Common values include ko-fi, paypal, buymeacoffee, patreon. Match against the row’s platform field if you need platform-specific logic.

Amount may be null when the donor did not provide it. Check before formatting.

Donation references are not verified payments. The logged-donation action fires for any submitted form, not just confirmed transactions. Do not use it to grant access, award subscription tier upgrades, or make financial decisions — use benecaster_donation_received for verified Stripe transactions.

Code

<?php
add_action( 'benecaster_before_donation_form', function ( int $show_id ): void {
    printf( '<p class="legal">%s</p>', esc_html__( 'Donations are non-refundable.', 'my-plugin' ) );
} );

add_action( 'benecaster_after_donation_confirmation', function ( int $show_id, float $amount, string $currency ): void {
    // Amount is 0/USD at server-render time. Use benecaster_donation_received
    // for the real per-donation amount, fired from the Stripe webhook.
    echo '<p><a href="/thanks/">Continue browsing →</a></p>';
}, 10, 3 );

add_action( 'benecaster_donation_received', function ( int $show_id, float $amount, string $currency, array $intent, int $donation_id ): void {
    // Real amount in major units (e.g. 15.00 USD), full PaymentIntent array.
    my_crm_log_donation( $show_id, $amount, $currency, $intent['id'] );
}, 10, 5 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →

Powered by