Skip to main content

benecaster_get_listener_support_donations()

Free 
benecaster_get_listener_support_donations( int $show_id, array $args = [] ): array

Returns a show’s Listener Support donations: one row per donation, oldest first. That covers donations taken through Stripe and the records supporters submit after giving on Ko-fi, PayPal or another platform.

Rows carry no donor name, email, message or reference. A chart needs none of them, and they stay on the donations screen.

Parameters

Name Type Default Required Description
show_id int — Yes WordPress post ID of the show.
args array [] No Optional. date_from and date_to — the window on the donation date, UTC and inclusive, as Y-m-d (the whole day) or Y-m-d H:i:s; no date_to means now.

Return Value

Type: array

One row per donation, oldest first: id, show_id, user_id (null for a guest donor, or once the person's data has been erased; the amount stays), platform (stripe, or the platform the supporter named), currency (ISO code, upper case, or null), amount_donated and donated_at (UTC). An empty list when there are none, or when a date is malformed.

Example

$rows = benecaster_get_listener_support_donations( $show_id, [
    'date_from' => gmdate( 'Y-m-01' ),
] );
$totals    = [];
$no_amount = 0;
foreach ( $rows as $row ) {
    if ( null === $row['amount_donated'] ) {
        $no_amount++; // a donation with no amount: count it, never add it as zero
        continue;
    }
    // Minor units, per currency: never add different currencies together.
    $totals[ $row['currency'] ] = ( $totals[ $row['currency'] ] ?? 0 ) + $row['amount_donated'];
}

Notes

amount_donated is in minor units as Stripe counts them (cents; yen as yen; 5000 for KWD 5.000; 500000 for UGX 5,000), in the row's own currency: the same unit as benecaster_get_membership_payments(), so the two can share a chart. Never add rows of different currencies together. It is null when a row has no amount or no currency, which a record submitted after giving on another platform can lack: count it as a donation, never as zero.

What it cannot tell you. Refunds are not recorded for donations, so a refunded donation is still listed. There is no live or test flag, so a test-mode Stripe donation looks like a real one. An amount a supporter submitted after giving elsewhere is what they typed, not a verified payment.

An empty early month can be a purge. Donations are kept indefinitely unless the podcaster sets a donation retention period, which deletes older rows nightly.

There is no capability check, and rows carry user IDs. Check manage_options, or your own capability, before showing them. A malformed date returns an empty list and raises a _doing_it_wrong() notice. See Chart Listener Support donations beside membership revenue.

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