Staging REST API

Endpoints for reading and managing the staging active subscriber set. All endpoints require manage_options capability and a valid X-WP-Nonce header.

Base path: benecaster/v1/staging/set

`GET /benecaster/v1/staging/set`

Returns the current staging active set — subscribers whose feed tokens are active on this staging domain.

Auth: manage_options + X-WP-Nonce

Response:

{
  "items": [
    {
      "user_id": 12,
      "email": "sarah@example.com",
      "display_name": "Sarah"
    }
  ],
  "count": 5,
  "cap": 25,
  "is_staging": true
}

Field notes:

Field	Notes
`items`	Subscribers currently in the staging active set.
`count`	Number of subscribers currently in the set.
`cap`	Maximum set size for this plan. `null` for Pro, Multi-Show, and Studio (unlimited).
`is_staging`	Always `true` on a recognized staging domain or when `BENECASTER_STAGING` is defined.

`POST /benecaster/v1/staging/set/add`

Adds a subscriber to the staging active set. If the set is at capacity (count === cap), returns a 409 error — the caller is expected to surface a swap UI.

Auth: manage_options + X-WP-Nonce

Body:

{
  "user_id": 42
}

Success response (201):

{
  "added": true,
  "user": {
    "user_id": 42,
    "email": "alex@example.com",
    "display_name": "Alex"
  },
  "count": 6
}

Error responses:

Code	HTTP	Meaning
`benecaster_staging_at_cap`	409	Set is at capacity. Remove a subscriber before adding another.
`benecaster_user_not_found`	404	No WordPress user with the given `user_id`.
`benecaster_already_in_set`	409	User is already in the staging active set.

When 409 benecaster_staging_at_cap is returned, the admin UI opens the swap modal — the user selects one staging-active subscriber to remove, then POST /set/remove and POST /set/add are called in sequence.

`POST /benecaster/v1/staging/set/remove`

Removes a subscriber from the staging active set. Their feed tokens remain in the database; feeds simply return empty from the staging domain after removal.

Auth: manage_options + X-WP-Nonce

Body:

{
  "user_id": 12
}

Success response (200):

{
  "removed": true,
  "count": 5
}

Error responses:

Code	HTTP	Meaning
`benecaster_not_in_set`	404	User is not currently in the staging active set.

`POST /benecaster/v1/staging/set/reset`

Rebuilds the staging active set from scratch using the default selection algorithm: at least 2 subscribers from each membership tier, filled to the plan cap by join date (oldest first). Existing set is replaced entirely.

Auth: manage_options + X-WP-Nonce

Body: None required.

Response (200):

{
  "reset": true,
  "items": [
    {
      "user_id": 12,
      "email": "sarah@example.com",
      "display_name": "Sarah"
    }
  ],
  "count": 25,
  "cap": 25
}

items reflects the new set after rebuilding. count and cap match the same semantics as GET /set.

Cap Behavior by Plan

The cap field returned by all endpoints reflects the subscriber limit for the staging active set:

Plan	`cap` value
Free / Starter / Growth	`25`
Pro / Multi-Show / Studio	`null` (unlimited)

When cap is null, POST /set/add never returns 409 benecaster_staging_at_cap — the set has no ceiling. The subscriber_count field in the daily validation payload is sent uncapped for unlimited plans; see Staging Mode Internals for the capping formula.