LifterLMS Custom Engagement Triggers: Award Achievements From Code
How the LifterLMS engagement engine works, how to register a custom engagement trigger that admins can configure, how to fire it reliably, and how to…
Read articleWhat a headless LifterLMS setup really involves: which parts the REST API covers, why lessons and completion need custom endpoints, how to authenticate safely, where checkout should live, and when a hybrid build is the smarter choice.
Headless LifterLMS means keeping LifterLMS and WordPress as the back end that stores courses, students and orders, while a separate JavaScript application, often built with Next.js, Nuxt or a mobile framework, renders what learners see. Teams consider it when they want an app-like learning experience, a single front end across several systems, or a modern development workflow.
It can work well, but it is more work than most people expect, because LifterLMS was built to render its own pages. This guide is for developers and technical leads scoping a headless build. It explains what the REST API covers and what it deliberately does not, gives you working custom endpoints for the gaps that matter most, and covers authentication, checkout, caching and SEO.
If you are new to the API itself, read our introduction to the LifterLMS REST API and webhooks first.
"Headless" covers a range of architectures. Choosing the right one early saves months.
| Approach | What the JavaScript app renders | What WordPress still renders | Effort |
|---|---|---|---|
| Decoupled marketing site | Home page, catalogue, course sales pages, blog | Checkout, student dashboard, lessons, quizzes | Moderate |
| Headless learning app | Catalogue, dashboard, lesson player, progress | Checkout, account management, often quizzes | High |
| Fully headless | Everything, including checkout and quizzes | Only the admin | Very high |
For most course businesses the first option delivers the benefits people actually want, such as fast public pages and a free choice of front-end stack, with little risk. The second suits products where learning is part of a larger application. The third means rebuilding a large part of LifterLMS in JavaScript and maintaining it through every update; it is rarely worth it.
All core routes live under /wp-json/llms/v1. For a headless front end, the useful ones are:
/courses, /memberships and /access-plans return published content, with prices, plans and the checkout details your sales pages need. Published courses can be read without authentication./courses/{id}/content lists a course's sections, and /sections/{id}/content lists a section's lessons./students/{id}, /students/{id}/enrollments and /students/{id}/progress/{post_id}. Reading other people's records needs staff capabilities.Two gaps shape every headless learning app:
/lessons resource grants read permission only to users who can edit lessons. That is a sensible default, since lesson access depends on enrollment, drip and prerequisites, but it means a student-facing app needs its own endpoint./students/{id}/progress/{post_id} requires permission to edit the course and the student. The Mark Complete button on the website uses a different route.There is also no checkout endpoint. Orders are created by the LifterLMS checkout form and the payment gateway add-ons, which is the main reason to keep checkout on WordPress.
The plugin below adds two routes under /wp-json/llmsx/v1. The first returns a lesson to a logged-in student only if LifterLMS would show it to them on the website. The second marks a lesson complete through the same action the Mark Complete button triggers, so quiz requirements and minimum lesson time still apply.
<?php
/**
* Plugin Name: LLMSX Headless Learning API
* Description: Student-facing lesson endpoints that respect LifterLMS access rules.
*/
defined( 'ABSPATH' ) || exit;
add_action( 'rest_api_init', function () {
$id_arg = array(
'id' => array(
'required' => true,
'sanitize_callback' => 'absint',
),
);
register_rest_route( 'llmsx/v1', '/lessons/(?P<id>\d+)', array(
'methods' => WP_REST_Server::READABLE,
'callback' => 'llmsx_rest_get_lesson',
'permission_callback' => 'is_user_logged_in',
'args' => $id_arg,
) );
register_rest_route( 'llmsx/v1', '/lessons/(?P<id>\d+)/complete', array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => 'llmsx_rest_complete_lesson',
'permission_callback' => 'is_user_logged_in',
'args' => $id_arg,
) );
} );
function llmsx_rest_get_lesson( WP_REST_Request $request ) {
$lesson = llms_get_post( $request['id'] );
$user_id = get_current_user_id();
if ( ! $lesson instanceof LLMS_Lesson ) {
return new WP_Error( 'llmsx_not_found', 'Lesson not found.', array( 'status' => 404 ) );
}
// Enrollment, drip, prerequisites and membership rules, exactly as on the website.
$restriction = llms_page_restricted( $lesson->get( 'id' ), $user_id );
if ( $restriction['is_restricted'] ) {
return new WP_Error(
'llmsx_restricted',
'You do not have access to this lesson.',
array( 'status' => 403, 'reason' => $restriction['reason'] )
);
}
$post = $lesson->get( 'post' );
return rest_ensure_response( array(
'id' => $lesson->get( 'id' ),
'title' => get_the_title( $post ),
'content' => do_shortcode( do_blocks( $post->post_content ) ),
'video' => $lesson->get_video(),
'course_id' => (int) $lesson->get( 'parent_course' ),
'next_id' => $lesson->get_next_lesson(),
'complete' => llms_is_complete( $user_id, $lesson->get( 'id' ), 'lesson' ),
) );
}
function llmsx_rest_complete_lesson( WP_REST_Request $request ) {
$lesson_id = $request['id'];
$user_id = get_current_user_id();
if ( ! llms_can_user_complete_lesson( $user_id, $lesson_id ) ) {
return new WP_Error( 'llmsx_forbidden', 'You cannot complete this lesson.', array( 'status' => 403 ) );
}
// Same path as the Mark Complete button, so quiz and minimum-time rules still apply.
do_action( 'llms_trigger_lesson_completion', $user_id, $lesson_id, 'lesson_' . $lesson_id, array() );
return rest_ensure_response( array(
'id' => $lesson_id,
'complete' => llms_is_complete( $user_id, $lesson_id, 'lesson' ),
) );
}
A few notes on the design:
llms_page_restricted() checks enrollment, drip dates, prerequisites and membership rules, and returns a reason when access is denied, which your app can use to show the right message.llms_can_user_complete_lesson() checks that the student is enrolled and the lesson is available. The llms_trigger_lesson_completion action then runs the lesson progression rules, so a lesson that requires a passing quiz is not completed early. Calling llms_mark_complete() directly would skip those checks.do_blocks() renders block content. If your lessons were written in the classic editor, wrap it in wpautop() as well. Shortcodes or blocks that rely on front-end scripts will need equivalents in your app.Quizzes are the next decision. Rebuilding the quiz player in JavaScript means reimplementing attempts, timers, resumption and grading rules. Most teams link out to the WordPress quiz page in a focused layout, or embed it, until there is a strong reason to rebuild.
How your app proves who the learner is matters more than anything else in a headless build.
| Method | Use it for | Avoid it for |
|---|---|---|
| LifterLMS API keys | Server-to-server calls from your own back end, such as building the catalogue at deploy time | Anything in the browser or a mobile app bundle |
WordPress cookie plus X-WP-Nonce | A front end on the same site, such as app.example.com next to example.com | Unrelated domains, where browsers will not send the cookie |
| Application passwords | Back-end services and tools acting as one user | End users typing a generated password into your app |
| Token plugins (JWT or OAuth) | Separate front ends and mobile apps with per-learner sign-in | Unmaintained plugins; check the one you choose |
LifterLMS API keys act as the WordPress user they belong to and only work over HTTPS. A key in client-side code is a key anyone can copy, with that user's permissions. The WordPress handbook page on REST API authentication covers cookies, nonces and application passwords. A common pattern is a small back end for your front end: the learner signs in through it, it holds the session, and it calls WordPress on their behalf.
Keep checkout on WordPress. The LifterLMS checkout handles access plans, coupons, taxes, payment plans, free trials and the gateway add-ons' payment forms, including 3D Secure challenges for Stripe. Rebuilding that in JavaScript, then keeping it in sync with gateway changes, is the riskiest part of any headless project.
In practice, your app's Enroll button links to the access plan's checkout URL, which the API returns as the plan's permalink. After payment, the student returns to your app, which reads their new enrollment through the API. LifterLMS webhooks such as enrollment.created and order.updated let your back end update its own records without polling. Account management, password resets and invoices can stay on WordPress pages styled to match your app.
If enrollments start in another system, for example after a sale in your own application, the API can enroll the student directly. Our guide to enrolling students from an external app covers that flow.
llms_page_restricted().llms_mark_complete() from an endpoint. It bypasses quiz and time requirements.Yes, with the REST API for catalogue, enrollment and progress data, plus a few custom endpoints for lesson content and completion. Checkout is best left on WordPress.
Not in core. The core API is REST. A GraphQL layer would need a third-party plugin or custom schema work.
Public pages usually are, because they can be static. Learning pages are only as fast as the API behind them, so performance work on WordPress still matters.
Yes, the same endpoints and authentication approach apply. Our overview of LifterLMS mobile app options compares building one with the alternatives.
Decide which of the three architectures you need before choosing a framework, and list the learner screens your app must render. If that list includes lessons and progress, budget for custom endpoints like the ones above and for an authentication design. Our LifterLMS development team designs and builds headless and hybrid LifterLMS projects, including the WordPress side that keeps them secure. Share your architecture sketch and we will review it with you.
How the LifterLMS engagement engine works, how to register a custom engagement trigger that admins can configure, how to fire it reliably, and how to…
Read article
When the built-in LifterLMS reporting is not enough: where the data lives, four ways to build custom reports, and a complete plugin that adds a…
Read article
How to build a custom LifterLMS payment gateway: the order lifecycle, the LLMS_Payment_Gateway methods you implement, a hosted-checkout skeleton with…
Read articleSkip the trial and error. Get specialist LifterLMS help and ship faster.