Skip to main content

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 →