Skip to main content

Bulk Enroll REST API

Required add-on: Core

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

Queues a bulk enrollment job. Only one job may run at a time per show — submitting while a job is active returns 409.

Request body:

{
  "token_type": "subscriber",
  "tier_slug": "gold",
  "emails": [
    "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.

emails — array of strings; maximum 1,000 entries. Blank or duplicate entries are ignored.

Response: 202 Accepted

{
  "job_id": "enroll_abc123",
  "total": 2,
  "status": "queued",
  "token_type": "subscriber"
}

Error codes:

Code Meaning
409 active_job_exists Another job is already running for this show
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 queued. 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 present and is neither subscriber nor follower
400 limit_exceeded More than 1,000 emails submitted

Get Job Status

GET /shows/{show_id}/subscribers/bulk-enroll/status?job_id={job_id}

Returns current progress for a running or recently completed job.

Response:

{
  "job_id": "enroll_abc123",
  "status": "running",
  "token_type": "subscriber",
  "total": 200,
  "processed": 87,
  "enrolled": 82,
  "skipped": 5,
  "errors": 0
}

status — one of queued, running, complete, failed.

token_type — the batch’s subscriber or follower choice, carried through from the submit request. Reads subscriber for an idle or pre-existing job record that predates this field.

Returns 404 when the job ID is not found (either never existed, or the completed job record has already been cleaned up).

Per-row outcomes and messages

Each processed address gets an outcome (created, skipped, or error, depending on endpoint version) and a message explaining it. Two values are new with follower batches:

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 queued; nothing was created for this address

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 →

Powered by