learndash/manage-achievement creates a new achievement badge or updates an existing one.
Status defaults to publish here rather than draft, which is the opposite of most creation abilities.
At a glance
| Ability | learndash/manage-achievement |
| Toolset | LearnDash — toolset/learndash |
| Group | LearnDash › Achievements |
| Requires | AcrossAI Pro, plus LearnDash LMS active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
The reason is that an achievement only fires when published. A draft badge is not a staged badge — it is an inert one, and a badge created as a draft and forgotten is a badge nobody ever earns.
Since there is no useful staging state, defaulting to draft would mostly produce silent failures.
The trigger decides what earns it, and must be a key from learndash/list-achievement-triggers.
Scope it with course_id, lesson_id, topic_id, quiz_id or group_id: a post ID restricts it, the string all is a wildcard, and omitting the key is right for triggers where it does not apply.
occurrences set to 0 means unlimited repeats, which is what makes a streak badge work.
Idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
action | string | Yes | create or update. |
achievement_id | integer | For update | Which achievement. |
title | string | For create | The badge name. |
trigger | string | For create | A key from learndash/list-achievement-triggers. |
points | integer | No | Points the badge carries. |
occurrences | integer | No | 0 for unlimited repeats. |
course_id | string | integer | No | A post ID to restrict, all as a wildcard, or omit. |
quiz_id | string | integer | No | As above. |
group_id | string | integer | No | As above. |
status | string | No — defaults to publish | An unpublished achievement never fires. |
What comes back
| Name | Type | What it is |
|---|---|---|
achievement | object | The achievement after the write. |
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:
Create a badge for completing the onboarding course.
It resolves to one call:
{
"ability": "learndash/manage-achievement",
"parameters": {
"action": "create",
"title": "Onboarding complete",
"trigger": "course_completed",
"course_id": 412,
"points": 10
}
}Worth knowing
- Published by default, because a draft badge is inert rather than staged.
- The trigger must exist on this site.
occurrences: 0means unlimited repeats.- An omitted scope key and
allare different.
Related abilities
- LearnDash List Triggers — valid trigger keys
- LearnDash Award Achievement — grant one manually
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category