Read or set an episode’s sponsors, the campaign each is tied to, and their ad positions from code, as the episode editor’s Sponsors tab does
The route behind the episode editor’s Sponsors tab: /benecaster-sponsor-manager/v1/shows/{show_id}/episodes/{episode_id}/sponsors. It is admin only (manage_options plus the X-WP-Nonce header). A show where Sponsor Manager is off is refused with 403 benecaster_sponsor_manager_not_active. An episode that is not that show’s, or is trashed, an auto-draft or a revision, is 404 benecaster_sponsor_manager_episode_not_found.
Each sponsor on an episode is tied to one of its campaigns on the episode’s show, or to none (campaign_id 0). A sponsor is a show’s sponsor by having a campaign there (see Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code).
-
The episode’s date picks the campaign a newly added sponsor starts on: its publish date if published, its scheduled date if scheduled, a draft’s own date if it has one, and today (site time zone) for a draft with no date and for a new episode. It only sets the default.
-
GETanswers200 { episode_date, items, available }.episode_dateis that date,YYYY-MM-DD.itemsis the episode’s sponsors in order, each{ sponsor_id, company, positions, archived, campaign_status, campaign_id, campaign, outside, campaigns }.positionsis a list ofpre_roll,mid_roll,post_roll, in that order.campaignis the tied campaign as a choice (below), ornullfor none.outsideis true when no offered campaign of the sponsor covers the episode’s date; the tab then warns Outside every {Sponsor} campaign on this show.campaignsis what the tie may be switched to: the sponsor’s active campaigns on the show, plus the tied one if it is archived.availableis the active sponsors with an active campaign on the show, company A–Z, each{ id, company, campaign_status, campaigns, default_campaign_id, outside }.default_campaign_idis the campaign covering the episode’s date when exactly one does,0when none does, andnullwhen several do (the caller must choose).- A choice is
{ id, name, start_date, end_date, status, archived, covers }, newest start first.coverssays whether it covers the episode’s date. campaign_statusis the sponsor’s standing on this show across its campaigns there.- Nothing here carries a contact or a rate.
-
GET /shows/{show_id}/episodes/new/sponsorsgives the same answer for an episode not saved yet:itemsis[]and campaigns are chosen as of today. The same403applies. -
PUTtakes{ sponsors: [ { sponsor_id, campaign_id, positions: [ … ] }, … ] }, the episode’s whole list in order. Acampaign_idof0, or none, is no campaign, and[]removes every sponsor. It answers likeGET. Changing only a campaign is a change. The request is refused whole with400 benecaster_sponsor_manager_invalid_assignment,data.indexnaming the entry at fault, for:- a list that is not a list, or has more than 50 entries
- a sponsor listed twice
- a sponsor with no campaign on the path’s show
- an archived sponsor, or one whose campaigns on the show are all archived, that the episode does not already have (one it already has may stay)
- a
campaign_idthat is not a whole number, or not one of that sponsor’s campaigns on the path’s show - an archived campaign the assignment is not already tied to (one it already holds may stay)
- no position, or a position that is not one of the three
A write the database refuses is
500. An episode outside every campaign is not refused. Sending the list already stored writes nothing and fires no hook. -
Hooks: benecaster_sponsor_manager_before_save_episode_sponsors and benecaster_sponsor_manager_after_save_episode_sponsors, both
( int $episode_id, int $show_id, array $sponsors, array $previous ), each list[ [ 'sponsor_id' => int, 'campaign_id' => int, 'positions' => string[] ], … ]in order. Theafterhook fires only when the write succeeded. -
When an episode moves to another show, both hooks fire too. Each sponsor with an active campaign on the destination show covering the episode’s date is kept and re-pointed to that campaign (the newest-starting when several do); every other sponsor is dropped.
$show_idis then the show the episode moved to,$sponsorsthe kept list with its newcampaign_ids ([]when none is kept), and$previousthe list before the move. This happens with Sponsor Manager off on every show too. Deleting an episode for good removes its sponsors with no hook; trashing keeps them. -
A new episode has no id until Benecaster’s first save. The tab reads
…/episodes/new/sponsors, holds the choice, campaign included, in the browser, and sends thePUTwhen Benecaster dispatchesbenecaster:episode-created(see Attach your add-on’s work to a new episode once it has been saved). Code that assigns sponsors itself does the same, or waits for benecaster_episode_created. The held campaign is saved as chosen, even if the first save gives the episode a date that campaign does not cover.
Read assignments through this route, or benecaster_sponsor_manager_get_episode_sponsors(), never from the table.
Code
<?php
// Tell an ad-ops sheet whenever an episode's sponsor line-up or campaigns change.
add_action( 'benecaster_sponsor_manager_after_save_episode_sponsors', function ( int $episode_id, int $show_id, array $sponsors, array $previous ): void {
$before = array_column( $previous, 'campaign_id', 'sponsor_id' );
foreach ( $sponsors as $entry ) {
if ( ( $before[ $entry['sponsor_id'] ] ?? null ) !== $entry['campaign_id'] ) {
my_adops_log( $show_id, $episode_id, $entry['sponsor_id'], $entry['campaign_id'] );
}
}
}, 10, 4 );
Hooks Used
Need this built rather than just documented? See our services →