LEARNTEC 2027Meet Virtualbadge.io in Karlsruhe in February 2027.Book a meeting at our stand
How-to guide

Moodle: issue certificates automatically on course completion

With the plugin for Moodle you issue certificates and badges from Virtualbadge.io automatically: on course completion, from a minimum grade or after release by a trainer. Your learners see the link right in the course.

30 minFor issuersUpdated November 2026
At a glanceGuide
in 7 steps
Time
about 30 minutes
For
Issuers
Where
In Moodle: Site administration Plugins Activity modules Virtualbadge, then in the course Add an activity or resource Virtualbadge
Plan
A plan with API access
What you need
  • Administrator rights in Moodle 4.5 to 5.3
  • An organization in Virtualbadge.io with API access
  • An active template and enough credits
  • A test account enrolled in the course as a student

No account yet? Start a free trial. It runs for seven days.

This guide is for Moodle administrators and trainers. The plugin adds the “Virtualbadge” activity to Moodle. It links a course to a template in Virtualbadge.io. When learners meet the condition, Moodle issues the credential in the background and shows the link in the activity. You keep setting the design, fields and email of the template in Virtualbadge.io, for example in the designer.

Requirements at a glance
ItemRequirement
MoodleVersion 4.5 to 5.3 with PostgreSQL, MariaDB or MySQL
OperationThe Moodle cron runs at least once a minute
NetworkOutbound HTTPS connection to api.virtualbadge.io, port 443. No inbound firewall rules are needed
Virtualbadge.ioAn organization with API access, at least one active template, enough credits
CourseCourse completion set up or a graded quiz, depending on the trigger

Step 1: Install the plugin in Moodle

You get the plugin's ZIP file from Virtualbadge.io. If you do not have it yet, write to us via the contact page.

Sign in to Moodle as an administrator and open “Site administration”, then “Plugins” and “Install plugins”. Upload the ZIP file and click “Install plugin from the ZIP file”. Confirm the validation, then choose “Upgrade Moodle database now”.

If installing from the interface is disabled on your server, your IT team unpacks the “virtualbadge” folder from the ZIP file into Moodle's “mod” directory, from Moodle 5.1 on into “public/mod”, and runs the upgrade.

Tip

An update works the same way: upload the new ZIP file and upgrade the database. Settings and issued credentials are kept.

Step 2: Enter the API key in Moodle

You create the key in Virtualbadge.io: open “Settings” and “Integrations” and click “Generate token” under “API Access”. Virtualbadge.io calls the key a token, the plugin calls it “API key”. The guide to the REST API shows the place.

In Moodle, open “Site administration”, “Plugins”, “Activity modules” and then “Virtualbadge”. Enter the token under “API key” and save. Moodle stores the key encrypted and afterwards only shows “(Set and encrypted)”.

Leave “API address” at https://api.virtualbadge.io. “Calls per hour” limits the calls per hour; the default is 200. Enter the limit agreed with Virtualbadge.io for your organization. “Date format” sets how dates appear in the template fields. The default is “DD.MM.YYYY”, that is day, month, year.

Plugin settings in Moodle: API address, API key and calls per hour.
Important

Treat the key like a password. It has the rights of your organization in Virtualbadge.io. If it may have fallen into the wrong hands, generate a new token in Virtualbadge.io and enter it in Moodle.

Step 3: Add the “Virtualbadge” activity to the course

Open the course and turn editing on. Click “Add an activity or resource” where you want the activity and choose “Virtualbadge”.

Give the activity a name, for example “Certificate Data protection training”. Your learners see the activity in the course under this name. A section of its own, such as “Certificates”, keeps the course tidy.

If the form says that the API key is not configured, step 2 is still missing.

“Add an activity or resource” with the “Virtualbadge” activity.

Step 4: Choose the template and map the fields

In the “Certificate or badge” section, choose the template under “Template”. The list shows the active templates of your organization. If you have just created or changed a template, “Reload templates” updates the list. What you have entered in the form is kept.

For each field of the template there is a row “Field” with the field's name. There you choose where the value comes from. The table lists the sources. The plugin always sends the person's name and email address, so they need no mapping.

If a template field has the same name as a field in Moodle, the source is preselected. Moodle sends dates in the date format you set.

“Certificate or badge” section: template, field mapping, trigger and email. Example with sample data.
Sources for the template fields
SourceExamplesValue
“Fixed text”“9 teaching units” or “Hamburg”The same for everyone. Placeholders such as {course} or {coursestartdate} are possible
“Participant”First name, last name, city, institution, custom profile fields such as an employee IDPer person, from the profile
“Course and completion”Course name, course ID number, course start and end date, custom course fields, completion date, course grade in percent, pointsFrom the course settings, the gradebook or the completion
“Grade items”Every grade item of the course, for example the final quiz in points or in percentThe person's result in this quiz or assignment
Important

If a mapped value is empty in Moodle, for example a missing course end date, nothing is issued. The status list then names the missing field. Fill in the course settings and custom course fields before the first learners complete the course.

Step 5: Set the trigger

Under “Issue on” you decide when Moodle issues. There are four triggers, and the table shows what they do.

“Email from Virtualbadge” is on unless you change it: Virtualbadge.io then sends an email with the link every time a credential is issued. Without the checkmark, your learners see the link in Moodle only. You set the text and sender of the email in Virtualbadge.io.

Save the activity. In the activity completion settings you can also choose the condition “Certificate issued”: the activity then counts as complete once the credential has been issued.

The four triggers
TriggerBehaviorGood for
“Course completion”As soon as Moodle marks the course as completed for the person. Course completion must be set up in the courseMandatory online training
“Course completion, after release by a trainer”The status list shows who has completed the course. The credential is issued only after “Release” or “Release all”. It carries the date of course completionA certificate a trainer checks first
“Minimum grade”As soon as the chosen grade reaches the percentage. Under “Grade” you choose “Course total” or a single quizA badge for a passed knowledge test
“Manual release by a trainer”Only after “Release” in the status list, independent of course completion. The credential carries the date of the releaseClassroom events
Tip

Several activities in one course are possible, for example a badge right after the quiz and a certificate after release. See the example under Mandatory training with a badge and a certificate.

Step 6: Check with a test person

Enroll a test account in the course as a student and meet the condition with it: complete the course, pass the quiz or have it released. Only people who may receive credentials in the course trigger issuing. By default these are the students. If a trainer completes the course as a trial, nothing happens.

Moodle issues in the background. At first the activity says “Your certificate is being created. The link will appear here shortly.” The status usually changes to “Issued” after 30 to 60 seconds. The test person then sees “Open certificate”, with download and sharing, and the link “Validation page” to the public validation page.

Every issue uses one credit, in a test as well.

What learners see after issuing: status “Issued”, “Open certificate” and “Validation page”. Example with sample data.
Tip

For a trial run without real credentials, use a Moodle test site and a sandbox organization in Virtualbadge.io with its own token. Credentials from the sandbox are marked as tests.

Step 7: Use the status list: release, resend, reissue

In the activity, trainers see all learners with their status under “Participants”. Depending on the trigger, you release there one by one with “Release”, for everyone who has completed the course with “Release all”, or for a selection with the checkboxes in front of the names.

If you added the activity to a running course, the list shows how many learners already meet the condition. “Issue to … participants” gives them their credential retroactively. With more than 50 people, Moodle works through them in the background.

If the email did not arrive, “Send email again” helps. If the name or course data are wrong, correct them in Moodle and then choose “Issue again”: a new credential with the current data is created, and the old one becomes invalid in Virtualbadge.io. All statuses and actions are listed under Status list: statuses and actions.

Status list “Participants” with issued and open credentials. Sample data with fictitious people.

Follow this guide with your own data.

Check the result

  • The templates of your organization appear in the activity form: the connection works.
  • The test person sees “Open certificate” and “Validation page” in the activity.
  • The status list shows “Issued” for the test person.
  • The person appears in Virtualbadge.io in the template's list of recipients.

More on this: Moodle integrationIntegrations

Example: mandatory training with a badge and a certificate

The screenshots in this guide come from a demo course: a data protection training with a page and a quiz with 5 questions and 20 points, passed from 16 points. The course counts as completed once the page has been viewed and the quiz passed. Two activities award a badge and a certificate.

Two activities in one course
SettingBadgeCertificate
Template in Virtualbadge.ioFields for course, points and maximum pointsFields for employee ID, date, course, course ID, teaching units, trainer and validity
Sources in Moodle“Course name”, “Course total (points)” and “Maximum course total (points)”A profile field, “Completion date”, “Course name”, “Course ID number” and three custom course fields
Trigger“Minimum grade” with 80 percent“Course completion, after release by a trainer”
ResultRight after the quiz, for example with 18 of 20 pointsAfter “Release”, with the date of course completion
Tip

If the credential should show the points of the questions, set the maximum grade of the quiz to the sum of the question points. Otherwise Moodle scales the points to the maximum grade.

Status list: statuses and actions

The list under “Participants” shows the status of each person and the buttons that go with it. The tables explain both.

Statuses in the list
StatusMeaning
“Not issued”Condition not met yet
“Queued”Will be sent shortly
“Being created”Created in Virtualbadge.io, the document is being generated. Usually changes to “Issued” after 30 to 60 seconds
“Issued”The credential has been issued
“Retrying”Virtualbadge.io was briefly not reachable or the call limit is reached. Moodle tries again by itself
“Error”Not issued. The reason is shown next to it
“Revoked”Revoked or replaced in Virtualbadge.io
“Deleted in Virtualbadge”Deleted in Virtualbadge.io. The link no longer works
Actions for trainers
ButtonWhenEffect
“Release”Manual release, or the course is completed and the trigger asks for a releaseIssues the credential
“Release all”Several people have completed the course. The button names their numberIssues to everyone who has completed the course
“Release selected” or “Issue to selected”Checkboxes in front of the names are tickedIssues only to the selected people
“Retry issuing”Status “Error”A new attempt, for example after a missing course end date has been entered
“Send email again”Status “Issued”Virtualbadge.io sends the email once more to the original address. No new credential, no credit, at most ten times
“Issue again”Status “Issued”A new credential with the current data from Moodle, the old one becomes invalid. Uses one credit
“Issue new certificate”Status “Deleted in Virtualbadge”A new credential with the current data. Uses one credit

“Issue again” needs changed data. If the name, email address and all field values are unchanged, the current credential stays valid and no credit is used. If the email address has changed, enter the new address in the profile and choose “Issue again”. “Send email again” always uses the original address.

Moodle checks issued credentials against Virtualbadge.io about once a day. If a credential is revoked or replaced there, the status list shows it. Moodle takes over a replaced credential with its new link.

If no credential is issued

If someone meets the condition but receives no credential, the reason is in the course under “Reports” and “Logs”, in the event “Certificate not issued”.

Reasons in the log
ReasonWhat to do
No email addressEnter an email address in the profile, then release or issue retroactively
Grade below the minimum gradeNothing is issued below the minimum grade. After a better result Moodle issues by itself
Not enrolled, may not receive credentials or cannot access the activityCheck the person's role. Also check that the activity is visible and has no restriction the person does not meet

For administrators, “Site administration”, “Reports”, “System status” shows the check “Virtualbadge certificates”: failed and retried issues from all courses, with the latest error and a link to the status list.

Important

If the activity reports that the template has fields that are not mapped, fields were added or renamed in Virtualbadge.io. Until they are mapped, the activity issues nothing. Open the form with “Edit settings”, click “Reload templates”, map the new fields and save. Then catch up on open issues with “Retry issuing”.

Privacy and operation

To issue a credential, the plugin sends the name, email address, completion date, the values of the mapped fields and a technical Moodle reference to Virtualbadge.io. The plugin declares this through the Moodle privacy API.

Moodle always opens the connection itself. Course completion does not wait for Virtualbadge.io: if the service is briefly not reachable, Moodle repeats the attempt up to ten times by itself. The reference per issue prevents duplicate credentials.

One credential takes two to three calls. With 200 calls per hour, that is about 70 to 100 credentials per hour. When the limit is reached, the plugin waits and continues as soon as calls are free again.

Deleting data in Moodle, resetting a course or uninstalling the plugin does not revoke any credentials. They stay valid until you revoke them in Virtualbadge.io.

Frequently asked questions

Which Moodle versions does the plugin work with?

Moodle 4.5 to 5.3, on PostgreSQL, MariaDB or MySQL. This guide describes version 1.1.4 of the plugin.

Does every issue use a credit?

Yes. Every issue and every reissue with “Issue again” or “Issue new certificate” uses one credit. Sending the email again uses none.

Can one course award a badge and a certificate?

Yes. Add two activities, each with its own template and trigger: for example a badge from 80 percent in the final quiz and a certificate after course completion.

Do learners who have already completed the course get a credential retroactively?

Yes. The status list shows how many people already meet the condition. “Issue to … participants” issues to them retroactively.

What happens if Virtualbadge.io is briefly not reachable?

Course completion in Moodle carries on as normal. The status list shows “Retrying”, Moodle tries up to ten times by itself and issues nothing twice.

What happens to the credentials when I reset the course?

On a course reset, the option “Delete issue records” deletes only the records in Moodle. The credentials stay valid in Virtualbadge.io. Whatever is issued afterwards is a new credential.

Can several organizations issue from one Moodle site?

Yes. In the plugin settings you add further organizations with their own key under “Organisations”, for example for a partner, and map them to course categories under “Course categories”. Courses without a mapping use the main organization.

Does this work without the plugin?

Yes. From other systems you issue with Zapier or the REST API, and for single course groups with a CSV list.

Where to go next

Try it with your own certificate

Upload your current certificate design, issue a test credential and follow the guides with real data. The trial runs for seven days.

More than 1,000 organizations issue with Virtualbadge.io, including telc, Vodafone, Dell, IDP, EBS Universität and Mannheim Business School.