Start Role Migration - Advanced User Role Editor for WordPress

Start Role Migration - Plugixa Advanced User Role Editor

POST /plugixa-aure/v1/users/migrate

Move every holder of one role to another, in the background. The first 200 accounts are processed during the request; the rest follow in batches of 200 about a minute apart, run by WP-Cron.

Needs the Edit people permission: plugixa_aure_edit_users. Part of the Users feature: when it is switched off in Settings the route is not registered and answers 404.

Note. The move runs on WP-Cron, so on a site with no visits, or with WP-Cron disabled and no real cron job, it waits after the first 200 accounts. Poll Get Role Migration to follow it.

Request

POST https://your-site.example/wp-json/plugixa-aure/v1/users/migrate

Request body

Content type: application/json

Field	Type	Required	Description
`from`	`string`	Yes	The role whose holders move.
`to`	`string`	Yes	The target role. You must hold every capability it grants.
`mode`	`string`	Yes	`add`: holders also get `to` and keep `from`. `replace`: they get `to` and lose `from`. `remove`: they lose `from`, and anyone for whom it was the only role gets `to`.

Outside add mode, the holders lose from, so you must also hold what from grants and be allowed to lift what it blocks. If you hold from yourself, the move is refused when it would remove your own access to the editor. A restore point is taken before the first batch.

{
  "from": "subscriber",
  "to": "customer",
  "mode": "replace"
}

Responses

`200` OK. `data` is the move after its first batch.

{
  "success": true,
  "data": {
    "state": "running",
    "from": "subscriber",
    "to": "customer",
    "mode": "replace",
    "total": 1250,
    "processed": 200,
    "changed": 200,
    "actor": 1,
    "started": "2026-11-12 09:30:00",
    "finished": "",
    "message": ""
  }
}

When everyone fits in the first batch, state is already done. The fields are those of Get Role Migration.

Errors

Status	Code	When
`400`	`rest_invalid_param`	`mode` is not `add`, `replace` or `remove`.
`404`	`plugixa_aure_unknown_role`	`from` or `to` does not exist.
`422`	`plugixa_aure_same_role`	`from` and `to` are the same role.
`409`	`plugixa_aure_migration_administrator`	`from` is Administrator in `replace` or `remove` mode.
`409`	`plugixa_aure_migration_running`	Another move is still running.
`409`	`plugixa_aure_no_holders`	Nobody would be changed: nobody holds `from`, or in `add` mode they all hold `to` already.
`403`	`plugixa_aure_cannot_grant`	The change grants, or lifts a block on, a capability you do not hold yourself.
`403`	`plugixa_aure_cannot_revoke`	The change takes away, or blocks, a capability you do not hold yourself.
`409`	`plugixa_aure_self_lockout`	The change would remove your own access to the editor.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-aure/v1/users/migrate" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"from":"subscriber","to":"customer","mode":"replace"}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-aure/v1/users/migrate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'from' => 'subscriber',
        'to'   => 'customer',
        'mode' => 'replace',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-aure/v1/users/migrate', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ from: 'subscriber', to: 'customer', mode: 'replace' }),
});
const { data } = await response.json();