Promote to Bridge REST API

Admin REST endpoints for the Promote to Bridge wizard and Promotion History panel. All endpoints require manage_options capability and a valid WP REST nonce.

Base path: /wp-json/benecaster/v1/shows/{show_id}/promote

Get Writable Bridge Targets

GET /shows/{show_id}/promote/targets

Returns all bridges that implement BridgeWritable — the destination options shown in the wizard’s first step. Each entry includes the bridge’s available tiers (external membership levels).

Response:

[
  {
    "slug": "memberpress",
    "name": "MemberPress",
    "tiers": [
      { "id": "1", "name": "Gold Membership" },
      { "id": "2", "name": "Silver Membership" }
    ]
  }
]

Preview a Promotion Run

GET /shows/{show_id}/promote/preview?target_bridge_slug={slug}&tier_map[native_slug]={external_id}

Returns subscriber counts per mapped tier without executing the run. Used by the wizard’s confirmation step to show how many subscribers will be affected.

Response:

{
  "tiers": [
    { "slug": "gold", "external_id": "1", "count": 47 },
    { "slug": "silver", "external_id": "2", "count": 23 }
  ],
  "total": 70
}

Run a Promotion

POST /shows/{show_id}/promote/run

Executes the promotion. Long-running for large subscriber lists; runs synchronously.

Request body:

{
  "target_bridge_slug": "memberpress",
  "tier_map": {
    "gold": "1",
    "silver": "2"
  },
  "grace_days": 30
}

Response: 200 OK

{
  "ok": true,
  "promoted": 68,
  "skipped": 2,
  "errors": 0,
  "grace_period_ends_at": "2026-07-28T00:00:00Z",
  "rows": [
    { "user_id": 12, "email": "alice@example.com", "status": "promoted" },
    { "user_id": 15, "email": "bob@example.com", "status": "skipped" }
  ]
}

Get Promotion History

GET /shows/{show_id}/promote/history

Returns all subscriber rows that have ever been through a promotion run, with current grace status.

Response — array of subscriber rows:

[
  {
    "subscription_id": 88,
    "user_id": 12,
    "email": "alice@example.com",
    "promoted_to_bridge": "memberpress",
    "grace_period_ends_at": "2026-07-28T00:00:00Z",
    "grace_status": "active"
  }
]

grace_status — one of active (within grace period), expired (token revoked), cleared (manually cleared by admin).

Clear a Grace Period

POST /shows/{show_id}/promote/history/{subscription_id}/clear-grace

Removes the grace period marker and re-enables the subscriber’s feed token. Used by the Promotion History panel’s “Clear grace” action.

Response: 200 OK with { "ok": true }.

Extend a Grace Period

POST /shows/{show_id}/promote/history/{subscription_id}/extend-grace

Request body:

{ "days": 14 }

Adds days to the subscriber’s grace period expiry. If already expired, extends from the current datetime.

Response: 200 OK with { "ok": true, "grace_period_ends_at": "2026-08-11T00:00:00Z" }.