Bulk Enroll REST API
REST endpoints for programmatic bulk subscriber enrollment. All endpoints require manage_options capability and a valid WP REST nonce.
Base path: /wp-json/benecaster/v1/shows/{show_id}/subscribers/bulk-enroll
Submit a Bulk Enrollment Job
POST /shows/{show_id}/subscribers/bulk-enroll
Starts a bulk enrollment job and answers with its status. A show runs one job at a time: submitting while the show’s job is running returns 409 active_job_exists.
Request body:
{
"token_type": "subscriber",
"tier_slug": "gold",
"billing_interval": "monthly",
"addresses": [
"alice@example.com",
"bob@example.com"
]
}
token_type — subscriber (default when omitted) or follower; any other value returns 400 rest_invalid_param.
tier_slug — required, and used, only when token_type is subscriber. Ignored for a follower batch.
billing_interval — monthly (default) or annual; any other value is read as monthly.
addresses — array of strings; at most 1,000 entries. Blank entries are ignored. An entry that starts with an apostrophe ahead of =, +, - or @ (as the subscriber CSV export writes such a value) loses that one apostrophe before it is checked, so '=name@example.com enrolls =name@example.com. An apostrophe in a real address (o'neil@example.com, 'neil@example.com) stays.
Response: 200, the same body as Get Job Status, for the job just started.
Error codes:
| Code | Meaning |
|---|---|
409 active_job_exists |
The show’s job is running, stalled ones included (resume it with …/resume instead). “A bulk enrollment is already running for this show. Wait for it to finish, or click Resume if it has stalled, then add the next list.” A running job whose stored list has gone does not block. A malformed request gets its own 400 first |
409 bridge_not_builtin |
A subscriber batch (including one with no token_type at all, which defaults to subscriber) was submitted on a show whose active membership bridge is not Built-in Membership — including a show with no bridge connected. Checked before tier_slug is validated, so an unrecognized tier on a non-built-in show returns this, not invalid_tier, and nothing is started. A follower batch is accepted on every bridge. Enabling benecaster_bridge_supports_manual_membership for a bridge does not unlock this — bulk enroll never calls the bridge |
400 invalid_tier |
tier_slug does not match an active native tier (subscriber batches only) |
400 rest_invalid_param |
token_type is neither subscriber nor follower; tier_slug is missing on a subscriber batch; or addresses holds no address |
400 too_many_addresses |
More than 1,000 addresses |
Get Job Status
GET /shows/{show_id}/subscribers/bulk-enroll/status
Reports the show’s current job. There is no job parameter: a show has one job at a time, and a show with no job answers status: idle with zero counts rather than 404.
Response:
{
"job_id": "enroll_abc123",
"token_type": "subscriber",
"status": "running",
"stalled": false,
"continuing": false,
"error_msg": null,
"total": 200,
"processed": 87,
"enrolled": 80,
"already_enrolled": 2,
"skipped": 5,
"errors": 0,
"rows": [
{ "email": "alice@example.com", "outcome": "created" },
{ "email": "not-an-address", "outcome": "skipped", "message": "invalid_email" }
]
}
status — idle, running, complete or failed. A job runs in slices of about 20 seconds, each carrying on from the last.
stalled — true when the job is running and nothing has moved for five minutes. Resume it with the endpoint below.
continuing — true while an open admin screen is keeping a stalled job moving after a resume, on a site where WP-Cron does not fire.
error_msg — why a failed job stopped, or null. A failed job is started again by submitting the same list: anyone it enrolled reads already_enrolled.
token_type — the batch’s subscriber or follower choice, carried through from the submit request.
rows — one entry per processed address: its email as enrolled (so without an apostrophe removed on submit), an outcome (created, already_enrolled, skipped or error) and, where there is one, a message.
Resume a Stalled Job
POST /shows/{show_id}/subscribers/bulk-enroll/resume
Runs the next ~20-second slice of a stalled job within the request, and answers with the status body above. It does nothing to a job that is moving normally. A running job whose stored list has gone is marked failed.
Per-row outcomes and messages
Each processed address gets an outcome and, where there is one, a message explaining it. Besides invalid_email:
message |
outcome |
Meaning |
|---|---|---|
follower_cap_reached |
skipped |
The show’s unlicensed 100-follower cap has been reached |
confirmation_sent |
created |
Double opt-in is on for followers; a confirmation email was sent instead of granting the follower token immediately |
bridge_not_builtin |
error |
The show was switched off Built-in Membership after this subscriber batch was started; nothing was created for this address |
interrupted |
error |
The job stopped on this address three times in a row, so it was left out and the job moved on. Check the address and add it alone. ⚠ On a show that asks followers to confirm, an address in progress when a run stops can receive its confirmation email twice |
Every row of a job caught by bridge_not_builtin carries it — the job reads status: complete, errors equals total, enrolled is 0. This is distinct from the POST’s own 409 bridge_not_builtin above, which refuses before anything is queued.
For a follower batch, already_enrolled means the address already holds a token — any type — for this show, not “has an active subscription” as it does for a subscriber batch.
See Also
Need this built rather than just documented? See our services →