LifterLMS Grades: How Course Grades Are Calculated and Read

How LifterLMS turns quiz attempts into lesson, course and overall grades, how Lesson Weight changes the result, where students and staff see grades, and how to read them through the REST API.

  • Add as a preferred source on Google
Illustration for “LifterLMS Grades: How Course Grades Are Calculated and Read”

LifterLMS grades look simple on screen: a percentage next to each course. Behind that number is a chain of rules that decides which attempts count, how lessons are weighted and what happens to quizzes a student has not taken yet. When a student or a client asks "why is my grade 72?", you need to know that chain.

This article explains how LifterLMS calculates lesson, course and overall grades, how to weight them, where students and staff can see them, and how developers can read them from the REST API added in LifterLMS 10.2. It also covers what LifterLMS does not do, so you can plan around it.

It assumes your courses already have quizzes. If they do not, start with how to create quizzes in LifterLMS.

How LifterLMS grades are built, from attempt to overall grade

There are four levels, each calculated from the one below:

  1. Quiz grade. The grade of the student's best graded attempt on that quiz. Incomplete and Pending Review attempts do not count until they are graded.
  2. Lesson grade. In core, a lesson's grade is the grade of its quiz. A lesson without a quiz has no grade. Add-ons can contribute too: the Assignments add-on, for example, lets assignment results count towards lesson grades.
  3. Course grade. A weighted average of the course's lesson grades, using each lesson's Lesson Weight.
  4. Overall grade. A simple average of the student's course grades across every course they are enrolled in that has a grade.

Grades are percentages rounded to two decimal places. When nothing has been graded yet, LifterLMS shows "N/A" rather than zero.

The attempt rules, including manual grading and resets, are covered in our article on quiz attempts, grading and results. This article starts at the lesson level.

Lesson Weight: how to weight course grades

In the course builder, open a lesson that has a quiz and you will find Lesson Weight in its settings, measured in points from 0 to 99. The tooltip says it "Determines the weight of the lesson when calculating the overall grade of the course." Every lesson starts at 1. The setting only appears on lessons with a quiz, or an assignment if you use that add-on, because a lesson without either has nothing to weight.

The calculation

For each lesson that has a numeric grade and a weight above zero, LifterLMS multiplies the grade by the lesson's share of the total weight, then adds the results together. A worked example with three quizzes:

LessonLesson WeightShare of totalGradeContribution
Module 1 check110%808.0
Module 2 check110%606.0
Final exam880%7560.0
Course grade10100%74.0

With the default weight of 1 everywhere, the same student would get the plain average, 71.67. Weighting lets the final exam matter more than the practice quizzes, which is usually what an assessor expects.

Two rules that change the result

  • Ungraded lessons are left out, not counted as zero. If a student has not attempted the final exam yet, the course grade is calculated from the module checks alone. A student halfway through a course can show a high grade that drops when the exam is taken.
  • A weight of 0 excludes the lesson. Use it for practice quizzes and surveys that should be recorded but never affect the course grade.

Plan weights before launch. Changing them later changes every student's course grade the next time it is calculated, including students who finished months ago.

Where students and staff see grades

Students

Students find grades in two places.

  • My Grades on the student dashboard. A table of their courses with Enrollment Date, Progress and Grade. Opening a course shows its progress, the course grade, the student's Overall Grade, latest achievement and last activity, followed by every section and lesson with the lesson grades.
  • The quiz page. After an attempt, the results screen shows that attempt's grade and a list of previous attempts.

The tab's address is set by the View Grades endpoint under Student Dashboard Endpoints in the LifterLMS account settings. Leave it blank to remove the tab if students should not see grades at all. Our student dashboard guide covers the other endpoints.

Staff, in reporting

Everything lives under LifterLMS > Reporting:

ScreenGrade shown
Students tab, main tableGrade: each student's overall grade. Sortable and included in the export
A single student, Courses tabThe student's grade in each course, and per-lesson detail inside a course
Courses tab, main tableAverage Grade across all students in each course
A single course, Students tabEach enrolled student's Grade in that course
Quizzes tabAverage Grade per quiz, and the grade of every attempt

Who sees what follows the view_grades rules. Administrators and LMS Managers can see everyone's grades. Instructors and assistants can see grades for students in courses they can edit. Students can only see their own.

For report design beyond these screens, see LifterLMS reporting and student progress.

Reading grades with the REST API

LifterLMS 10.2 added a read-only grades endpoint:

curl "https://example.com/wp-json/llms/v1/students/123/grades?course=456" \
  -u "ck_your_key:cs_your_secret"

It returns one item per course with the student_id, the course post_id, the course grade and a lessons array. Each lesson has its id, title, grade and a quiz object with the quiz id, the best attempt's grade, its attempt_id and its status. Grades are null where nothing has been graded. Leave out course to get every course the student is enrolled in, or pass several IDs separated by commas.

Students can read their own grades. Anyone else needs the reporting capability and permission to view that student, which in practice means an API key tied to an administrator or LMS Manager. The same release added a read-only grade field to the student progress endpoint and registered a student grades ability for the WordPress Abilities API.

Typical uses are nightly exports to an HR system, a school's student information system, or a reporting database. The LifterLMS REST API reference documents every field.

Working with grades in PHP

Inside WordPress, ask the student object. get_grade() returns a number, or the string "N/A" when there is nothing to grade:

add_shortcode( 'llmsx_course_grade', 'llmsx_course_grade_shortcode' );
function llmsx_course_grade_shortcode( $atts ) {
	$atts    = shortcode_atts( array( 'course_id' => get_the_ID() ), $atts );
	$student = llms_get_student();
	if ( ! $student ) {
		return '';
	}
	$grade = $student->get_grade( absint( $atts['course_id'] ) );
	if ( ! is_numeric( $grade ) ) {
		return esc_html__( 'No grade yet', 'llmsx' );
	}
	return esc_html( sprintf( '%s%%', llms()->grades()->round( $grade ) ) );
}

Use $student->get_overall_grade() for the overall figure. To change the maths, filter llms_calculate_course_grade or llms_calculate_lesson_grade; to change rounding, filter llms_grade_rounding_precision.

Grades are cached per student. Since LifterLMS 10.2 that cache is cleared automatically when a lesson is completed or marked incomplete, a quiz is completed, or an enrollment is deleted, including on sites using a persistent object cache such as Redis. If you change grades by other means in custom code, calculate with caching off (pass false as the third argument to llms()->grades()->get_grade()) or clear the student's cache.

What LifterLMS grading does not do

Be clear with clients about the limits of the core gradebook:

  • No minimum course grade for completion. A course completes when its lessons are complete, whatever the course grade. To enforce a standard, require a passing grade on a final exam lesson and make the following lessons depend on it.
  • No letter grades or grade scales. Grades are percentages. Mapping 90+ to "Distinction" needs a small customization.
  • No manual override of a course grade. Staff change grades by grading or deleting quiz attempts, not by typing a new course grade.
  • No graded items outside quizzes in core. Assignments add-on aside, there is nowhere to record a grade for an offline task. A custom graded post type can plug into the grading filters if you need one.
  • The overall grade is not weighted. A two-lesson taster course counts as much as a forty-lesson diploma.

Common mistakes

  • Leaving every Lesson Weight at 1. Fine for knowledge checks, wrong for courses with a final exam.
  • Reading a mid-course grade as a final result. Unattempted quizzes are excluded, so early grades can look better than they will end up.
  • Using the overall grade in certificates or contracts. It averages unrelated courses. Use the course grade.
  • Changing weights after students finish. Grades recalculate. Export historic results first if they matter.

Frequently asked questions

Does LifterLMS have a gradebook?

It has the data a gradebook needs: per-quiz, per-lesson, per-course and overall grades, visible to students under My Grades and to staff in reporting and the REST API. It does not have a spreadsheet-style screen for editing grades.

Why does a student's course grade show N/A?

None of the lessons with a quiz have a graded attempt yet, or every graded lesson has a weight of 0.

Can I put the course grade on a certificate?

Not with the built-in certificate merge codes, which cover student details, site details, dates and certificate IDs. A small custom merge code or shortcode can add it.

Can I export grades?

Yes. The Students reporting table export includes the overall grade, and the REST API returns course and lesson grades for any integration.

What to do next

Write down how you want a course grade to work, then set Lesson Weight to match and test it with a test student who passes some quizzes and skips others. If the numbers surprise you, they will surprise your students too.

If you need letter grades, a minimum grade to complete, grades on certificates or grades sent to another system, those are well-understood customizations. Our LifterLMS customization service builds them on top of the core grading API, and you can tell us how your grading should work.

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