LifterLMS Custom Reports: How to Build the Reports You Actually Need

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 Completions tab with date filters and CSV export to LifterLMS Reporting.

  • Add as a preferred source on Google
Illustration for “LifterLMS Custom Reports: How to Build the Reports You Actually Need”

Sooner or later every serious course business asks a question the standard screens cannot answer. How many people completed each course last quarter? Which cohort finished the compliance module before the deadline? What share of buyers never started? LifterLMS custom reports are how you answer those questions without exporting spreadsheets every Monday.

This guide is for developers and technically minded site owners. It explains what the built-in reporting covers, where the underlying data lives, how to choose between a spreadsheet, the REST API and a custom report inside WordPress, and it gives you a complete plugin that adds a Completions tab with date filters and CSV export to LifterLMS > Reporting.

What the built-in LifterLMS reporting covers

LifterLMS > Reporting has six tabs: Students, Courses, Memberships, Quizzes, Sales and Enrollments. Between them you can see each student's progress and grades, each course's students, quiz attempts, and sales and enrollment charts over a date range. Our guide to LifterLMS reporting and student progress walks through each screen.

The gaps tend to be the same on every site:

  • Cross-course summaries. One table with every course, its enrollments and completions for a period.
  • Business segments. Results by company, department, region or custom registration field.
  • Deadlines and compliance. Who has not finished by a given date.
  • Combined data. Course activity next to revenue, CRM stage or support tickets.
  • Scheduled delivery. A report emailed to a manager every week.

Some of these are covered by add-ons. The paid Groups add-on gives group leaders reporting for their own members, for example. Check that first; it is cheaper than custom code.

Where the reporting data lives

Most course reporting comes from a small number of places. Our article on the LifterLMS data model goes deeper; for reporting, these are the ones that matter:

QuestionSourceKey detail
When did a student enroll?wp_lifterlms_user_postmeta, rows with meta_key _start_dateThe date is in the updated_date column.
What is their enrollment status now?Same table, _status rowsValues such as enrolled, expired and cancelled; the newest row wins.
What have they completed?Same table, _is_complete = yesRows exist for lessons, sections and courses; filter by post type.
How did they enroll?Same table, _enrollment_triggerPurchases look like order_123.
Quiz resultswp_lifterlms_quiz_attemptsGrade, status, attempt number and dates per attempt.
RevenueOrder and transaction posts and their metaUse the order and transaction objects rather than raw meta where you can.
Logins and page activitywp_lifterlms_eventsGrows quickly on busy sites.

For per-student values, prefer the model methods over SQL: llms_get_student( $user_id ) returns an object with get_progress(), get_grade(), get_enrollment_date() and get_completion_date(), which respect LifterLMS's own caching. For lists, LLMS_Student_Query and LLMS_Query_User_Postmeta are the classes the core reports use. For summaries across thousands of rows, one well-indexed SQL query is usually the fastest option, as in the example below.

Four ways to build custom LifterLMS reports

ApproachGood forWatch for
Export to a spreadsheetOccasional questions, small sitesManual, error-prone, out of date by Tuesday
REST API into a BI or sheet toolTeams that already use Looker Studio, Power BI or Google SheetsPaging through large lists; read-only API keys
A custom tab in LifterLMS ReportingReports admins check often, with the same permissions as the rest of the LMSCode you own; query performance
A reporting database or warehouseLarge sites, data from several systems, history beyond what WordPress keepsBuild and running cost; sync design

The REST API exposes students, enrollments, progress, grades, orders and quiz attempts under /wp-json/llms/v1, documented in the LifterLMS REST API reference, which suits the second option. Our guide to LifterLMS reporting in Google Sheets shows that route. The rest of this article builds the third.

Build a custom tab in LifterLMS Reporting

LifterLMS builds its reporting menu from the lifterlms_reporting_tabs filter and renders each tab through the action llms_reporting_content_{tab}. It checks access with a capability that the lifterlms_reporting_tab_cap filter can change. That is everything you need to add a native-looking report.

The plugin below adds a Completions tab. It shows, for any date range, how many enrollments started and how many course completions happened in each course, and offers the same data as a CSV download. Save it as a plugin file in wp-content/plugins/llmsx-completions-report/ and activate it.

<?php
/**
 * Plugin Name: LLMSX Completions Report
 * Description: Adds a Completions tab to LifterLMS > Reporting with CSV export.
 */

defined( 'ABSPATH' ) || exit;

const LLMSX_REPORT_TAB = 'llmsx-completions';
const LLMSX_REPORT_CAP = 'view_others_lifterlms_reports';

// 1. Register the tab, visible only to users who may see everyone's data.
add_filter( 'lifterlms_reporting_tabs', function ( $tabs ) {
	if ( current_user_can( LLMSX_REPORT_CAP ) ) {
		$tabs[ LLMSX_REPORT_TAB ] = __( 'Completions', 'llmsx' );
	}
	return $tabs;
} );

// 2. Require the same capability when the tab URL is opened directly.
add_filter( 'lifterlms_reporting_tab_cap', function ( $cap, $tab ) {
	return ( LLMSX_REPORT_TAB === $tab ) ? LLMSX_REPORT_CAP : $cap;
}, 10, 2 );

// Read and validate the date range from the URL (site timezone).
function llmsx_report_dates() {
	$start = isset( $_GET['start'] ) ? sanitize_text_field( wp_unslash( $_GET['start'] ) ) : '';
	$end   = isset( $_GET['end'] ) ? sanitize_text_field( wp_unslash( $_GET['end'] ) ) : '';
	$valid = '/^\d{4}-\d{2}-\d{2}$/';

	if ( ! preg_match( $valid, $start ) ) {
		$start = wp_date( 'Y-m-d', strtotime( '-30 days' ) );
	}
	if ( ! preg_match( $valid, $end ) ) {
		$end = wp_date( 'Y-m-d' );
	}
	return array( $start, $end );
}

// 3. One grouped query, cached for an hour.
function llmsx_report_rows( $start, $end ) {
	global $wpdb;

	$key  = 'llmsx_completions_' . md5( $start . $end );
	$rows = get_transient( $key );
	if ( false !== $rows ) {
		return $rows;
	}

	$rows = $wpdb->get_results(
		$wpdb->prepare(
			"SELECT p.ID AS course_id, p.post_title AS course,
				SUM( m.meta_key = '_start_date' ) AS enrollments,
				SUM( m.meta_key = '_is_complete' AND m.meta_value = 'yes' ) AS completions
			FROM {$wpdb->prefix}lifterlms_user_postmeta AS m
			INNER JOIN {$wpdb->posts} AS p ON p.ID = m.post_id AND p.post_type = 'course'
			WHERE m.meta_key IN ( '_start_date', '_is_complete' )
				AND m.updated_date BETWEEN %s AND %s
			GROUP BY p.ID, p.post_title
			ORDER BY completions DESC",
			$start . ' 00:00:00',
			$end . ' 23:59:59'
		),
		ARRAY_A
	);

	set_transient( $key, $rows, HOUR_IN_SECONDS );
	return $rows;
}

// 4. Render the tab inside the LifterLMS Reporting screen.
add_action( 'llms_reporting_content_' . LLMSX_REPORT_TAB, function () {
	list( $start, $end ) = llmsx_report_dates();
	$csv_url = wp_nonce_url(
		add_query_arg( compact( 'start', 'end' ) + array( 'action' => 'llmsx_completions_csv' ), admin_url( 'admin-post.php' ) ),
		'llmsx_completions_csv'
	);
	?>
	<form method="get">
		<input type="hidden" name="page" value="llms-reporting">
		<input type="hidden" name="tab" value="<?php echo esc_attr( LLMSX_REPORT_TAB ); ?>">
		<input type="date" name="start" value="<?php echo esc_attr( $start ); ?>">
		<input type="date" name="end" value="<?php echo esc_attr( $end ); ?>">
		<button class="button">Filter</button>
		<a class="button" href="<?php echo esc_url( $csv_url ); ?>">Download CSV</a>
	</form>
	<table class="widefat striped">
		<thead><tr><th>Course</th><th>Enrollments</th><th>Completions</th></tr></thead>
		<tbody>
		<?php foreach ( llmsx_report_rows( $start, $end ) as $row ) : ?>
			<tr>
				<td><?php echo esc_html( $row['course'] ); ?></td>
				<td><?php echo absint( $row['enrollments'] ); ?></td>
				<td><?php echo absint( $row['completions'] ); ?></td>
			</tr>
		<?php endforeach; ?>
		</tbody>
	</table>
	<?php
} );

// 5. CSV export through admin-post.php, with capability and nonce checks.
add_action( 'admin_post_llmsx_completions_csv', function () {
	if ( ! current_user_can( LLMSX_REPORT_CAP ) ) {
		wp_die( esc_html__( 'You are not allowed to export this report.', 'llmsx' ) );
	}
	check_admin_referer( 'llmsx_completions_csv' );

	list( $start, $end ) = llmsx_report_dates();

	header( 'Content-Type: text/csv; charset=utf-8' );
	header( 'Content-Disposition: attachment; filename="completions-' . $start . '-' . $end . '.csv"' );

	$out = fopen( 'php://output', 'w' );
	fputcsv( $out, array( 'Course ID', 'Course', 'Enrollments', 'Completions' ) );
	foreach ( llmsx_report_rows( $start, $end ) as $row ) {
		fputcsv( $out, $row );
	}
	fclose( $out );
	exit;
} );

How it works

  1. The tab is added only for users with view_others_lifterlms_reports, the capability LifterLMS already requires for its Sales and Enrollments tabs. Instructors, who can see reports for their own courses, do not see it.
  2. The capability filter applies the same rule when someone opens the tab's URL directly, so hiding the menu item is not the only protection.
  3. The query reads enrollments from _start_date rows and completions from _is_complete rows, joined to course posts, grouped per course.
  4. The result is cached in a transient for an hour, so reloading the screen does not repeat the query.
  5. The CSV export runs through admin-post.php and the admin_post_{$action} hook with a nonce and the same capability check, and streams the file without loading a page.

Dates in updated_date are stored in the site's timezone, which is why the defaults use wp_date(). A student who enrolls twice in the same course, for example after an expiry, has two _start_date rows, so treat the enrollment figure as "enrollments started in the period" rather than unique students. Adjust the query to COUNT( DISTINCT m.user_id ) if you need unique people.

Making custom reports fast and safe

  • Aggregate in SQL, not PHP. Looping over every student and calling get_progress() is fine for 50 people and painful for 50,000.
  • Cache the result, and clear it when it matters. An hour is fine for management reports. For live dashboards, clear the transient on lifterlms_course_completed or llms_user_enrolled_in_course.
  • Test against production-sized data. Run EXPLAIN on your queries using a copy of the live database. The user postmeta table is indexed on user_id and post_id; a report that filters only by meta_key and date scans more rows.
  • Move heavy reports off the request. If a report takes more than a few seconds, build it in the background with Action Scheduler and email or store the result. Our article on slow LifterLMS admin and reports covers the wider performance picture.
  • Respect permissions. If instructors should see a report, limit its rows to their courses with llms_get_instructor()->get_courses( array( 'posts_per_page' => -1 ), 'ids' ), and never show other instructors' students.
  • Treat exports as personal data. CSV files leave your site. Include only the columns the reader needs and follow your privacy policy on where they are stored.

Common report ideas and where their data comes from

  • Not started. Enrolled students with no _is_complete lesson rows in the course: a good list for a nudge email.
  • Overdue. Enrolled before a cut-off date and no course completion row: the core of a compliance report.
  • Time to complete. The difference between a student's _start_date and course _is_complete dates, averaged per course.
  • Quiz difficulty. Average grade and pass rate per quiz from the quiz attempts table, to find questions that need rewriting.
  • Revenue by course. Completed transactions grouped by the product on their order, compared with completions to see which paid courses are actually finished.
  • Segment reports. Any of the above grouped by a user meta field saved from your registration form, such as company or job role.

Frequently asked questions

Can I add a custom report to the LifterLMS Reporting menu?

Yes. Add a tab with the lifterlms_reporting_tabs filter and output its content on the llms_reporting_content_{tab} action, as in the plugin above.

Can LifterLMS email reports on a schedule?

Not out of the box. A custom plugin can build a report with Action Scheduler or WP-Cron and email it, or an automation tool can pull data from the REST API on a schedule.

Is it safe to query the LifterLMS tables directly?

For reading, yes, if you use $wpdb->prepare() and accept that table details may change between major versions. Never write to them directly; use LifterLMS functions such as llms_enroll_student() so hooks and caches stay correct.

Will a custom report survive LifterLMS updates?

A report in its own plugin that uses public hooks, functions and documented tables generally does. Test it on staging when LifterLMS releases a major version.

What to do next

Write down the three questions you most often wish your reports answered, and who needs each answer. That list tells you whether you need a spreadsheet, an API feed or a custom tab. If you want reports built into your LifterLMS admin, scheduled exports or a reporting database that combines LMS and sales data, our LifterLMS plugin development team builds them. Send us your report wish list and we will suggest the simplest way to deliver it.

Add LifterLMS Expert to your preferred sources

Add lifterlmsexpert.com as a preferred source on Google, or open this article in your AI assistant to use it as a source.

  • Add as a preferred source on Google
Free consultation

Prefer expert help over DIY?

Skip the trial and error. Get specialist LifterLMS help and ship faster.

Talk to a LifterLMS Expert Explore our services

Replies within one business day