Listener Support Settings REST API

REST endpoints for reading and writing Listener Support configuration. All endpoints require manage_options + a valid X-WP-Nonce header. These endpoints live on the benecaster/v1 namespace on the main WordPress installation.

---

GET /benecaster/v1/listener-support/settings

Returns the current Listener Support configuration. Pass ?show_id=N to also receive the per-show override state and effective merged values.

Auth: manage_options + X-WP-Nonce

Query parameters:

Response:

{
  "site": {
    "enabled":      true,
    "style":        "floating",
    "intent":       "non-subscribers",
    "payment_url":  "https://ko-fi.com/mypodcast",
    "button_label": "Support the show",
    "message":      "Enjoying the podcast? A small tip keeps it going."
  },
  "show": {
    "show_id":          5,
    "override_enabled": true,
    "overrides": {
      "payment_url":  "https://ko-fi.com/show2",
      "button_label": "Support Season 3"
    },
    "effective": {
      "enabled":      true,
      "style":        "floating",
      "intent":       "non-subscribers",
      "payment_url":  "https://ko-fi.com/show2",
      "button_label": "Support Season 3",
      "message":      "Enjoying the podcast? A small tip keeps it going."
    }
  }
}

The show key is only present when ?show_id=N is supplied.

Field reference — site object:

Field reference — show object:

---

POST /benecaster/v1/listener-support/settings

Saves site-wide Listener Support settings. Pass any subset of the site keys — unknown keys are silently dropped.

Auth: manage_options + X-WP-Nonce

Request body:

{
  "enabled":      true,
  "style":        "inline",
  "intent":       "all",
  "payment_url":  "https://ko-fi.com/mypodcast",
  "button_label": "Buy me a coffee",
  "message":      ""
}

All fields are optional. Fields omitted from the body are left unchanged.

Response: The saved site object — same shape as in GET /settings.

Validation:

Invalid values for style and intent return HTTP 400. Other fields with invalid values are sanitized to their default.

---

POST /benecaster/v1/listener-support/settings/show/{id}

Saves per-show Listener Support overrides for show {id}.

Auth: manage_options + X-WP-Nonce

Route parameter:

Request body:

{
  "override_enabled": true,
  "overrides": {
    "payment_url":  "https://ko-fi.com/show-specific-page",
    "button_label": "Support this show"
  }
}

override_enabled controls whether the per-show values replace site defaults. When false, the overrides object is stored but not applied — the show renders with site defaults until override_enabled is set back to true.

Pass only the keys you want to override in overrides. Keys absent from overrides are treated as “use site default for this setting.” To clear a previously set override, pass the key explicitly with its default value rather than omitting it.

Response: The saved show object including freshly computed effective values — same shape as in GET /settings?show_id=N.

Example — disable Listener Support for one show while keeping it active site-wide:

{
  "override_enabled": true,
  "overrides": {
    "enabled": false
  }
}

Example — reset a show to site defaults (remove all overrides):

{
  "override_enabled": false,
  "overrides": {}
}