learndash/revoke-achievement removes badges a learner has earned. It requires confirm_user_email matching the learner.
The ID distinction is the thing to get right.
Before you run it
The award records are deleted outright and the learner’s points total drops. It takes award_ids — the per-award row IDs from learndash/list-user-achievements, not achievement post IDs. A learner can hold the same badge more than once and each earn is a separate record, so passing the wrong kind of ID either fails or removes the wrong thing.
At a glance
| Ability | learndash/revoke-achievement |
| Toolset | LearnDash — toolset/learndash |
| Group | LearnDash › Achievements |
| Requires | AcrossAI Pro, plus LearnDash LMS active on the site |
| Capability | manage_options |
| Safety | Destructive and irreversible — award records are deleted and the learner’s points drop. Requires confirm_user_email. |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
An achievement post ID identifies the badge definition. An award ID identifies one learner earning it once. This takes the second.
That matters because a repeatable badge produces many awards, and revoking “the badge” is not a coherent instruction — you are removing specific earns.
learndash/list-user-achievements returns those IDs.
The points drop accordingly, by the points recorded on each award at the time it was made — which may not match the badge’s current points value.
Deleting the achievement definition itself is a different and much wider operation. learndash/delete-achievement with permanent deletion erases every award of that badge for every learner on the site.
Not idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
learner | string | integer | Yes | User ID, login or email. |
award_ids | array | Yes | Per-award row IDs from learndash/list-user-achievements. |
confirm_user_email | string | Yes | Must match the learner’s email address. |
confirm | boolean | Yes — must be true | The irreversibility gate. Without it the call is refused before anything is touched. |
What comes back
| Name | Type | What it is |
|---|---|---|
revoked | integer | How many awards were removed. |
points_removed | integer | How far the learner’s total dropped. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Take back that badge I awarded by mistake.
It resolves to one call:
{
"ability": "learndash/revoke-achievement",
"parameters": {
"learner": "sam@example.com",
"award_ids": [4412],
"confirm_user_email": "sam@example.com"
}
}Worth knowing
- Award IDs, not achievement post IDs.
- Each earn of a repeatable badge is a separate record.
- Points drop by what was recorded at award time.
- Deleting the definition is a far wider operation.
Related abilities
- LearnDash List User Achievements — get the award IDs
- LearnDash Delete Achievement — the site-wide version
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category