Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code, as the Sponsors screen does
The routes behind Benecaster → Sponsors, under /benecaster-sponsor-manager/v1.
A sponsor is one record for the whole site; its campaigns belong to a show. The sponsor holds what is the same everywhere: company, contact and notes. Each campaign holds one show’s name, dates and rate. A sponsor may have several campaigns on one show, overlapping or not, and campaigns on any number of shows. A sponsor is a show’s sponsor by having a campaign there.
Every route is admin only (manage_options plus the X-WP-Nonce header), and the routes exist only while Sponsor Manager is on for at least one show.
Sponsors (site-wide, no show in the path)
GET /sponsorsanswers200 { items }: the site’s active sponsors, company A–Z (at most 500), sponsors with no campaign included. Witharchived=1, the archived ones instead. Withsearch=…, only companies containing it (case-insensitive).GET /shows/{show_id}/sponsorsanswers200 { items }: a show’s sponsors, meaning the active sponsors with at least one active campaign on the show, company A–Z. Each is a sponsor (below) pluscampaign_status, its standing on this show across its active campaigns there:runningif any is running, elsenone(a campaign with no dates),upcoming,ended, in that order. Witharchived=1, the rest of the sponsors with a campaign on the show instead (archived sponsors, and sponsors whose campaigns there are all archived), withcampaign_statustaken over all their campaigns there. Between them, the two lists hold each sponsor with a campaign on the show exactly once. This is the one sponsor route under a show, so it answers403 benecaster_sponsor_manager_not_activewhere Sponsor Manager is off.- A sponsor is
{ id, company, contact_name, contact_email, notes, archived, shows }.showsis every show it has a campaign on (archived campaigns included), each{ id, title }, lowest id first: the shows a contact change reaches.GET /sponsors/{id}and every write also carrycampaigns: every campaign of the sponsor on every show, archived ones included, newest start first, each a campaign (below) plusshow_title. A sponsor carries the contact’s email (and, withcampaigns, the rates), so never pass it to anything public. POST /sponsorstakes{ company, contact_name?, contact_email?, notes? }and answers201with the sponsor. Nothing else is stored on a sponsor: a show, dates or a rate sent here are ignored.PUT, PATCH /sponsors/{id}changes only the keys sent and answers200. A contact change applies on every show the sponsor has campaigns on.- Refusals are
400 benecaster_sponsor_manager_invalid_fieldwithdata.field:companyempty or over 200 characters;contact_nameover 200;contact_emailnot an email address (an empty one is allowed);notesover 5,000 characters. An id that is not a sponsor is404 benecaster_sponsor_manager_sponsor_not_found. POST /sponsors/{id}/archiveandPOST /sponsors/{id}/restoreanswer200with the sponsor. Archiving hides the sponsor on every show (lists and episode pickers) and never deletes it or its campaigns. There is no delete route.
Campaigns (under /shows/{show_id}/)
A show where Sponsor Manager is off is refused with 403 benecaster_sponsor_manager_not_active. A campaign of another show is 404 benecaster_sponsor_manager_campaign_not_found, the same answer as one that does not exist, even when it is the same sponsor’s.
-
GET /shows/{show_id}/campaignsanswers200 { items, default_currency }: the show’s active campaigns, newest start first (at most 1,000). Witharchived=1, its archived ones. Withsponsor_id=…, one sponsor’s.default_currencyis the currency of the show’s most recently saved campaign, elseUSD. -
A campaign is
{ id, sponsor_id, show_id, name, start_date, end_date, currency, rate_type, rate_by_position, rate_minor, rates: { pre_roll, mid_roll, post_roll }, archived, status, sponsor: { id, company, archived } };sponsorisnullif the sponsor post is gone.- Dates are
YYYY-MM-DDcalendar dates in the site’s time zone, inclusive, or''when open. rate_typeisflat(rate_minoris the campaign’s total) orper_episode: one amount per episode inrate_minor, or, withrate_by_position, one amount per ad position inrates(an episode carrying several positions costs their sum).- Every amount is an integer in the currency’s smallest unit (cents), or
nullwhen not agreed (0is an agreed rate of nothing). The rate is stored in its one shape: amounts that do not apply to it readnull. statusisupcoming,running,endedornone(no dates), as of today in the site’s time zone.- A campaign carries the rate, so never pass it to anything public.
- Dates are
-
POST /shows/{show_id}/campaignstakes{ sponsor_id, name, start_date?, end_date?, currency?, rate_type?, rate_by_position?, rate_minor?, rates? }and answers201with the campaign. The show is the path’s. Without a currency it takesdefault_currency.PUT, PATCH …/campaigns/{id}changes only the keys sent (the sponsor and the show never change); sending any rate key rewrites the whole rate in its shape. It answers200. -
Refusals are
400 benecaster_sponsor_manager_invalid_fieldwithdata.field:sponsor_idnot a sponsor, or an archived sponsor (restore it first)nameempty or over 200 charactersstart_dateorend_datenot a realYYYY-MM-DDdate, orend_datebefore the start (checked against the stored date for the one not sent)currencynot three letters, or empty on an updaterate_typenotflatorper_episoderate_minornot a whole number of at most 12 digits (sendnullor''for none)ratesnot an object, or one of its amounts not a whole number (data.positionnames it)
A write the database refuses is
500 benecaster_sponsor_manager_write_failed. -
POST …/campaigns/{id}/archiveandPOST …/campaigns/{id}/restoreanswer200with the campaign. Archiving hides the campaign on its show only and never deletes it; episodes already assigned keep their sponsor.
Hooks
They fire for writes made through these routes. A refused request fires nothing, and a failed write fires the before hook alone. Archiving or restoring into the state already held writes nothing and fires nothing.
- benecaster_sponsor_manager_before_save_sponsor
( int $sponsor_id, array $fields )and benecaster_sponsor_manager_after_save_sponsor( int $sponsor_id, array $fields, bool $created ).$sponsor_idis0before a create. - benecaster_sponsor_manager_before_archive_sponsor and benecaster_sponsor_manager_after_archive_sponsor
( int $sponsor_id, bool $archived ). - benecaster_sponsor_manager_rest_sponsor
( array $data, int $sponsor_id ), a filter over each sponsor a route returns. - benecaster_sponsor_manager_before_save_campaign
( int $campaign_id, int $show_id, array $fields )and benecaster_sponsor_manager_after_save_campaign( int $campaign_id, int $show_id, array $fields, bool $created ).$campaign_idis0before a create. - benecaster_sponsor_manager_before_archive_campaign and benecaster_sponsor_manager_after_archive_campaign
( int $campaign_id, int $show_id, bool $archived ). - benecaster_sponsor_manager_rest_campaign
( array $data, int $campaign_id ), a filter over each campaign a route returns.
Read sponsors and campaigns through these routes, never from the benecaster_sponsor posts’ meta or the campaigns table.
Code
<?php
// Copy each new campaign into a CRM the podcaster uses, with its show.
add_action( 'benecaster_sponsor_manager_after_save_campaign', function ( int $campaign_id, int $show_id, array $fields, bool $created ): void {
if ( $created ) {
my_crm_add_deal( $campaign_id, $show_id, $fields['name'], $fields['start_date'], $fields['end_date'] );
}
}, 10, 4 );
Hooks Used
-
benecaster_sponsor_manager_before_save_sponsor -
benecaster_sponsor_manager_after_save_sponsor -
benecaster_sponsor_manager_before_archive_sponsor -
benecaster_sponsor_manager_after_archive_sponsor -
benecaster_sponsor_manager_rest_sponsor -
benecaster_sponsor_manager_before_save_campaign -
benecaster_sponsor_manager_after_save_campaign -
benecaster_sponsor_manager_before_archive_campaign -
benecaster_sponsor_manager_after_archive_campaign -
benecaster_sponsor_manager_rest_campaign
Need this built rather than just documented? See our services →