Skip to main content

Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code, as the Sponsors screen does

Premium Intermediate Sponsor Manager

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 /sponsors answers 200 { items }: the site’s active sponsors, company A–Z (at most 500), sponsors with no campaign included. With archived=1, the archived ones instead. With search=…, only companies containing it (case-insensitive).
  • GET /shows/{show_id}/sponsors answers 200 { 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) plus campaign_status, its standing on this show across its active campaigns there: running if any is running, else none (a campaign with no dates), upcoming, ended, in that order. With archived=1, the rest of the sponsors with a campaign on the show instead (archived sponsors, and sponsors whose campaigns there are all archived), with campaign_status taken 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 answers 403 benecaster_sponsor_manager_not_active where Sponsor Manager is off.
  • A sponsor is { id, company, contact_name, contact_email, notes, archived, shows }. shows is 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 carry campaigns: every campaign of the sponsor on every show, archived ones included, newest start first, each a campaign (below) plus show_title. A sponsor carries the contact’s email (and, with campaigns, the rates), so never pass it to anything public.
  • POST /sponsors takes { company, contact_name?, contact_email?, notes? } and answers 201 with 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 answers 200. A contact change applies on every show the sponsor has campaigns on.
  • Refusals are 400 benecaster_sponsor_manager_invalid_field with data.field: company empty or over 200 characters; contact_name over 200; contact_email not an email address (an empty one is allowed); notes over 5,000 characters. An id that is not a sponsor is 404 benecaster_sponsor_manager_sponsor_not_found.
  • POST /sponsors/{id}/archive and POST /sponsors/{id}/restore answer 200 with 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}/campaigns answers 200 { items, default_currency }: the show’s active campaigns, newest start first (at most 1,000). With archived=1, its archived ones. With sponsor_id=…, one sponsor’s. default_currency is the currency of the show’s most recently saved campaign, else USD.

  • 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 } }; sponsor is null if the sponsor post is gone.

    • Dates are YYYY-MM-DD calendar dates in the site’s time zone, inclusive, or '' when open.
    • rate_type is flat (rate_minor is the campaign’s total) or per_episode: one amount per episode in rate_minor, or, with rate_by_position, one amount per ad position in rates (an episode carrying several positions costs their sum).
    • Every amount is an integer in the currency’s smallest unit (cents), or null when not agreed (0 is an agreed rate of nothing). The rate is stored in its one shape: amounts that do not apply to it read null.
    • status is upcoming, running, ended or none (no dates), as of today in the site’s time zone.
    • A campaign carries the rate, so never pass it to anything public.
  • POST /shows/{show_id}/campaigns takes { sponsor_id, name, start_date?, end_date?, currency?, rate_type?, rate_by_position?, rate_minor?, rates? } and answers 201 with the campaign. The show is the path’s. Without a currency it takes default_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 answers 200.

  • Refusals are 400 benecaster_sponsor_manager_invalid_field with data.field:

    • sponsor_id not a sponsor, or an archived sponsor (restore it first)
    • name empty or over 200 characters
    • start_date or end_date not a real YYYY-MM-DD date, or end_date before the start (checked against the stored date for the one not sent)
    • currency not three letters, or empty on an update
    • rate_type not flat or per_episode
    • rate_minor not a whole number of at most 12 digits (send null or '' for none)
    • rates not an object, or one of its amounts not a whole number (data.position names it)

    A write the database refuses is 500 benecaster_sponsor_manager_write_failed.

  • POST …/campaigns/{id}/archive and POST …/campaigns/{id}/restore answer 200 with 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.

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 );

View on GitHub →

Hooks Used

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