Preview as Tier REST API

Three endpoints for activating, reading, and clearing the “Preview as Tier” admin feature. Preview mode lets an admin see the subscriber-facing front end exactly as a subscriber at a specific tier would see it — including episode access, locked states, player visibility, and episode archive. Preview is scoped to a show and tier and stored as a session cookie; it never affects what actual subscribers see.

All three endpoints require manage_options and a valid X-WP-Nonce header.

---

GET /benecaster/v1/tools/preview-tier

Returns the current preview state for this admin session.

Auth: manage_options + X-WP-Nonce

Response (active preview):

{
  "active": true,
  "show_id": 45,
  "tier_slug": "basic",
  "show_title": "The Deep Dive",
  "tier_name": "Basic"
}

tier_name is the tier’s display name — the plan name on a show using Benecaster’s built-in membership, or the mapped tier’s name on a show using a membership plugin.

Response (no active preview):

{
  "active": false
}

---

POST /benecaster/v1/tools/preview-tier

Activates preview mode for a specific show and tier.

Auth: manage_options + X-WP-Nonce

Body:

{
  "show_id": 45,
  "tier_slug": "basic"
}

tier_slug is a tier on that show: a plan’s slug on a show using Benecaster’s built-in membership, or a mapped tier’s slug on a show using a membership plugin. Both work.

Read the valid slugs from GET /benecaster/v1/shows/{id}/availability-tiers, the same list the top-bar Preview as tier menu offers. It covers both kinds of show and includes the show’s Public tier, which previews what a signed-out visitor sees, without signing out. A tier you have retired is listed too, because its members still receive what is scheduled for it. Don’t use GET /shows/{id}/tiers for this: it lists membership-plugin tier mapping only, so it is empty on a built-in-membership show.

Response:

{
  "active": true,
  "show_id": 45,
  "tier_slug": "basic",
  "show_title": "The Deep Dive",
  "tier_name": "Basic"
}

Errors:

How it works:

Activating preview sets a session cookie benecaster_preview_tier containing {"show_id": 45, "tier_slug": "basic"}. The PreviewTierManager class hooks benecaster_episode_is_accessible and benecaster_user_tier_for_show — when the cookie is present and the admin is viewing the show’s front end, both filters return values as if the current user holds a token at the preview tier. Existing subscribers are not affected; the preview only applies to the admin’s own browser session.

A preview mode banner is displayed to the previewing admin and is not visible to anyone else.

The show page’s Subscribe section follows the preview too. [benecaster_subscribe] describes the previewed tier rather than your own plan:

• Previewing a paid tier: You are subscribed to …, with no plan cards, as a member at that tier sees it.
• Previewing a free tier: You are on the … plan., followed by the paid plans’ cards.
• Previewing Public: no panel and every card, as a signed-out visitor sees it.

That panel is the section’s only mention of the previewed tier. The preview banner still names it.

---

DELETE /benecaster/v1/tools/preview-tier

Clears the active preview. Removes the benecaster_preview_tier session cookie.

Auth: manage_options + X-WP-Nonce

Response:

{
  "active": false
}

Calling this endpoint when no preview is active returns the same response — it is idempotent.

Preview is also cleared on logout. The session cookie is tied to the admin’s session; logging out clears it automatically regardless of whether this endpoint is called.

---

Filters

Preview mode works by hooking two filters. These filters fire during normal episode access evaluation — add-on code that filters benecaster_episode_is_accessible or benecaster_user_tier_for_show will interact with preview mode. If your add-on also hooks these filters, make sure it respects values already set by PreviewTierManager rather than overriding them unconditionally.