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:

---

POST /benecaster/v1/staging/set/add

Adds a subscriber to the staging active set. The set is first in, first out: if it is at capacity (count === cap), the subscribers who have been in it longest are taken out to make room, and the response lists them in dropped. Adding a subscriber who is already in the set changes nothing and succeeds with an empty dropped.

Auth: manage_options + X-WP-Nonce

Body:

{
  "user_id": 42
}

Success response (200):

{
  "added": true,
  "user": {
    "user_id": 42,
    "email": "alex@example.com",
    "display_name": "Alex",
    "tier_slug": "supporter",
    "tier_name": "Supporter"
  },
  "dropped": [
    {
      "user_id": 12,
      "email": "sarah@example.com",
      "display_name": "Sarah",
      "tier_slug": "supporter",
      "tier_name": "Supporter"
    }
  ],
  "count": 25
}

The admin screen names the subscribers in dropped in its confirmation message. Taking the oldest out first can leave a tier with nobody staging-active; POST /set/reset puts every tier back.

Error responses:

---

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
}

Removing a subscriber who is not in the set changes nothing and still returns 200.

Error responses:

---

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:

When cap is null, POST /set/add never takes anyone out — the set has no ceiling. When the set already holds more subscribers than cap, for example after a plan change lowered it, the newest cap subscribers are kept the next time the set is used. The subscriber_count field in the daily validation payload is sent uncapped for unlimited plans; see StagingManager for the capping formula.