benecaster_entitlement_grant_slugs

Lets an add-on sell access that core knows nothing about. Return the named sets (a product or a bundle) a listener is entitled to and give each slug availability rows exactly as a tier has them: the listener’s feed becomes whatever it would otherwise be, plus those episodes.

A returned slug still needs availability rows. It is compiled exactly like a tier slug, so the filter says who is entitled and the availability rows say to what. A slug with no rows resolves fine and carries nothing, and there is no error to explain it, so check this first when a buyer sees no change.

Everything returned here is owned outright. It survives an over-limit demotion, a licence grace period and the end of the listener’s membership, and it keeps a lapsed member’s feed alive instead of letting them be refused. That makes this the wrong place for access that should end when a membership ends. That is what a buy-up is, and buy-ups reach the feed through the same slug list by a different route. A subscription upsell registered here would keep being granted after the subscription it rides on has gone.

The filter is add-only. Core’s own entitlement rows are merged back in after your callback runs, so removing a slug from the array does nothing: an add-on must not be able to revoke access core recorded on somebody’s behalf. To end a grant Benecaster holds, call EntitlementRepository::revoke_grant() or let its expires_at pass.

It runs on every authenticated feed request. Keep the callback to an indexed lookup, not an HTTP call, and cache your own answer if you need to.

A slug is a named set shared by every holder, never a per-person episode list. The feed cache is keyed by slug, so a per-buyer slug would mean a cache entry per buyer.

What core does with your return value. A return that is not an array is discarded with a _doing_it_wrong() notice and core’s own slugs are served. Entries that are not strings are dropped rather than cast.

There is no licence check on the filter, deliberately. When a licence lapses, the licence gate refuses the whole token feed before assembly is reached, so gating here would only move where the failure appears.

<?php
add_filter(
    'benecaster_entitlement_grant_slugs',
    function ( array $slugs, int $user_id, int $show_id ): array {
        // Your own record of what this person owns on this show. Return the
        // NAMED sets they are entitled to — a product or a bundle — never a
        // per-person list of episode IDs.
        foreach ( my_addon_products_owned( $user_id, $show_id ) as $product_slug ) {
            $slugs[] = $product_slug;
        }

        return $slugs;
    },
    10,
    3
);