Skip to main content

benecaster_get_membership_payments()

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

Returns what a show’s built-in membership has actually collected: one row per paid Stripe invoice, from Benecaster’s revenue ledger. It records what was charged at the time, so a later price change does not rewrite past revenue.

Benecaster records a payment when Stripe reports the invoice paid, and records refunds against it when Stripe reports a refund (see benecaster_stripe_charge_refunded).

Parameters

Name Type Default Required Description
show_id int — Yes WordPress post ID of the show.
args array [] No Optional. tier_slug — one tier only. date_from and date_to — the window on the payment date, UTC and inclusive, as Y-m-d (the whole day) or Y-m-d H:i:s; no date_to means now. mode — live, the default, since a test-mode charge is not revenue; test; or any.

Return Value

Type: array

One row per paid Stripe invoice, oldest first: id, show_id, user_id (null once the person's data has been erased; the amounts stay), tier_slug (the tier the invoice paid for), stripe_invoice_id, stripe_mode, billing_reason (Stripe's), currency (ISO code, upper case), amount_paid, amount_tax, amount_buyups, amount_refunded, paid_at and refunded_at (UTC). An empty list when there are none, or when a date or mode is malformed.

Example

$rows = benecaster_get_membership_payments( $show_id, [
    'date_from' => gmdate( 'Y-m-01' ),
] );
$net = [];
foreach ( $rows as $row ) {
    // Minor units, per currency: never add different currencies together.
    $net[ $row['currency'] ] = ( $net[ $row['currency'] ] ?? 0 )
        + $row['amount_paid'] - $row['amount_tax'] - $row['amount_refunded'];
}

Notes

Amounts are in minor units (cents; yen as yen), in the row's own currency. A show can charge in more than one currency, so never add rows of different currencies together. amount_paid includes tax; amount_tax and amount_buyups are the parts of it that were tax and buy-up lines, so the tier's own revenue is amount_paid - amount_tax - amount_buyups. amount_refunded is the total refunded so far. A payment for an upgrade is credited to the tier the subscriber moved to.

Nothing from before Benecaster began recording is here, and it cannot be rebuilt. Call benecaster_get_membership_payments_recorded_since() and label the chart "recorded since …" rather than drawing zero before that date.

Refunds are recorded only if the show's Stripe webhook sends charge.refunded.

There is no capability check, and rows carry user IDs. Check manage_options, or your own capability, before showing them. A malformed date or mode returns an empty list and raises a _doing_it_wrong() notice. See Chart built-in membership revenue from what was actually charged.

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