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,
"caps": [],
"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). |
caps |
[] when the site’s shows are on one license, which is the normal case. If they are on two licenses (Benecaster no longer allows this, but an older connection can still hold it), one row per license: shows (each { "id", "title" }), cap (an integer, or null for uncapped) and count, the staging-active subscribers counted against that license. A subscriber with feeds on both licenses’ shows counts in both rows, so the rows can add up to more than the top-level count. The top-level cap is then the first connected show’s license. |
is_staging |
true on a recognized staging domain, or when BENECASTER_STAGING is set to true in wp-config.php. BENECASTER_IS_PRODUCTION set to true overrides both. |
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
}
| Field | Notes |
|---|---|
dropped |
Subscribers taken out of the set to make room, oldest first. Each item has the same shape as user. An empty array when nobody was taken out. |
count |
Number of subscribers in the set after the change. |
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:
| Code | HTTP | Meaning |
|---|---|---|
rest_invalid_param |
400 | user_id is missing or not a positive integer. |
benecaster_staging_at_cap |
409 | The plan’s staging cap is 0, so no subscriber can be added. |
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:
| Code | HTTP | Meaning |
|---|---|---|
rest_invalid_param |
400 | user_id is missing or not a positive integer. |
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,
"caps": []
}
items reflects the new set after rebuilding. count, cap and caps 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 |
|---|---|
| Launch | 10 |
| Starter / Growth | 25 |
| Pro / Multi-Show / Studio | null (unlimited) |
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.
See Also
Need this built rather than just documented? See our services →