Members for Ko-fi

By trudslev

10+ active installationsVersion 1.7.1

Integrate with Ko-fi to manage WordPress users or roles via webhook.

Description

Members for Ko-fi is a WordPress plugin that integrates with Ko-fi to manage WordPress users and roles based on Ko-fi webhooks. This plugin allows you to automate user role assignments, log donations (in a database table), and manage memberships seamlessly.

Features:
– Automatically assign roles to users based on Ko-fi donations or memberships.
– Log user actions, such as donations and role changes, in a dedicated database table (no file logging).
– Lightweight debug logging to the PHP error log when WP_DEBUG is enabled.
– Stores only what it needs, and removes it all when you uninstall.

Use Cases:
– Reward your Ko-fi supporters with exclusive access to content or features.
– Automate user role management for subscription-based memberships.
– Track and log user activity for better insights.

License

This plugin is licensed under the GPLv3 or later. See the GNU General Public License for more details.

Installation

  1. Upload the plugin files to the /wp-content/plugins/members-for-kofi directory, or install the plugin through the WordPress plugins screen directly.
  2. Activate the plugin through the ‘Plugins’ screen in WordPress.
  3. Configure the plugin under Members for Ko-fi in the main admin menu (it has its own entry, with a heart icon).
  4. Set up your Ko-fi webhook to point to your WordPress site.

FAQ

How do I set up the Ko-fi webhook?

  1. Log in to your Ko-fi account and open the webhooks page: https://ko-fi.com/manage/webhooks
  2. Set the webhook URL to your site followed by /webhook-kofi, for example https://your-site.com/webhook-kofi.
  3. Copy the Verification Token (under Advanced) into Members for Ko-fi > Settings in WordPress.

How do I test my setup without waiting for a real payment?

Ko-fi’s webhook page has test buttons that send a real request to your site. Use them, then open Members for Ko-fi > Logs and check both the Request log and the User log.

The buttons all use the same fake supporter, Jo Example (jo.example@example.com), so a successful test creates a real WordPress user with that address. Delete it when you are done.

What each button sends:

  • Send single tip test – a one-off tip of 3.00 USD, with no tier.
  • Send first monthly test – a first subscription payment of 3.00 USD, with no tier.
  • Send membership tier test – a renewal subscription payment of 5.00 USD for the tier named Bronze.

I ran a test and nothing happened. Why?

Three settings decide whether a test does anything, and all three are working as intended when a test appears to be ignored:

  • “Only process subscription payments” is enabled. The single tip test is not a subscription payment, so it is ignored on purpose. Use the first monthly or membership tier test instead. The Request log will still show the request arriving with a 200, and the User log will say “Ignored non-subscription payment”.
  • You use tier mappings but have no matching tier. Only the membership tier test sends a tier name, and the name it sends is Bronze. If you want that test to assign a role, add a mapping for a tier called Bronze. Without it, the plugin falls back to your default role.
  • You have no default role set. The single tip and first monthly tests send no tier at all, so they can only ever use the default role. If that is empty and you rely purely on tier mappings, the supporter is still created as a WordPress user and the donation is still logged – only the role is skipped. The User log will show “User created” and “Donation received” but no “Role assigned”.

If the Request log is completely empty after a test, the request never reached WordPress. Check that the webhook URL in Ko-fi matches your site exactly, then open that URL in a browser:

  • {"error":"Method not allowed"} is the correct response. The endpoint only accepts the POST requests Ko-fi sends, and refuses anything else so that crawlers cannot fill your logs. Seeing this means the address is working.
  • A “Not Found” or 404 page means the endpoint is not registered. Re-save your permalinks under Settings > Permalinks to rebuild the rule, then try again.

A test says “Unauthorized” or “Missing verification token”. What now?

The verification token in Members for Ko-fi > Settings must match the one on Ko-fi’s webhook page exactly. If you have ever regenerated it on Ko-fi, paste the new value into the plugin as well – Ko-fi will not warn you that the two no longer match, and real payments will be rejected the same way the test was.

What happens when a supporter’s role expires?

Each time a payment arrives, the plugin records the date. If that date falls
further in the past than the number of days you configure, a daily job removes
the role it assigned and stops tracking it. Their WordPress account stays, and
so does any other role they have – only the role this plugin gave them is taken
away.

Set the number of days longer than your Ko-fi billing cycle, not equal to
it. Ko-fi sends a webhook once when a payment happens and never retries, so if
one delivery is lost – a brief outage, a network problem – the next one is a
whole month away. With a 30-day setting, a single lost delivery costs that
supporter their access. Something around two billing cycles absorbs it: the
next successful payment refreshes the date before anything is removed.

Why does a supporter have two roles?

The plugin adds its role to whatever the supporter already has, rather than
replacing it. New accounts get whatever WordPress assigns new users (usually
Subscriber), and the plugin’s role is added on top. When the role expires, only
the plugin’s role is removed, which leaves the account intact.

Can another plugin or theme show a user’s Ko-fi membership?

Yes. Since 1.4.0, members_for_kofi_get_membership( $user_id ) returns null if this plugin never gave the user a role, or an array describing the membership:

  • status: 'active' while the membership has not lapsed and the user holds the role, otherwise 'none'.
  • role: the role the membership grants.
  • managed: false if the user already had that role before paying for it. The plugin then never removes it.
  • subscription: true for a subscription payment, false for a one-off donation, null if unknown (payments made before 1.4.0).
  • member_since: Unix time of the first payment that gave the role. It stays the same through renewals, and someone who lets their membership lapse and later rejoins keeps their original date. null if unknown (memberships that began before 1.4.0).
  • last_payment_at: Unix time of the last payment.
  • expires_at: Unix time access lapses (or lapsed) without a new payment, or null when expiry is turned off.
  • manage_url and cancel_url: where the supporter manages or cancels on Ko-fi.
  • cancel_hint: short instructions for cancelling.

A membership that has ended is still reported, with status 'none', so an account page can say when it ended. For memberships that began before 1.4.0, the real start date can be filled in with WP-CLI, for example from the SinceDateUTC column of Ko-fi’s supporter export: wp members-for-kofi member-since set <user-id> "2024-03-05 18:20:00" (read as UTC; add --force to replace a recorded date). Check that the function exists before calling it, in case this plugin is inactive. The whole array passes through the members_for_kofi_get_membership filter, for example to change the links or the wording.

Can another plugin change what a payment does?

Yes. Since 1.6.0 the webhook has filters to skip a payment (members_for_kofi_process_payment), refuse to create an account (members_for_kofi_create_account, for example to keep a member who deleted their account from being re-created), change the role (members_for_kofi_role) and adjust a new account (members_for_kofi_new_user_args). It also has actions for an account created, a role assigned or removed, and a payment logged. A filter can never grant administrator or another role with site-running powers, and a broken callback never turns a payment into an error. The README on GitHub lists every hook with its arguments and examples.

What happens if a supporter changes their email address?

Since 1.5.0 their membership carries on. Ko-fi keeps sending the address the supporter gave Ko-fi, so the plugin remembers the addresses a member used before and matches payments to them. Before 1.5.0, the next payment created a second account under the old address, and the real account’s role expired. Members who changed their address before updating are not covered, because the old address was never recorded: ask them to use the same address on Ko-fi and on the site.

Other plugins can check for this with function_exists( 'members_for_kofi_supports_email_change' ) && members_for_kofi_supports_email_change().

Does this plugin delete data on deactivation?

No, the plugin does not delete any data on deactivation. However, you can manually delete data by uninstalling the plugin.

What personal data does this plugin store?

Two tables of its own:

  • User log – the WordPress user ID, email address, what happened (user created, role assigned, role removed, donation received), the role, and the amount and currency.
  • Request log – the email address, tier name, amount, currency, the HTTP status, and the request Ko-fi sent. The verification token is never stored.

Both are removed when you uninstall the plugin, along with its settings. Deactivating keeps them.

On a supporter’s account it keeps what their membership needs: the role it gave and when, when they first joined, the last payment, and the email addresses they used before changing theirs, so Ko-fi’s payments still reach the account.

All of it is covered by WordPress’s Export Personal Data and Erase Personal Data tools (Tools menu). Erasing keeps what a live membership needs, and says so; it is removed when the membership ends.

Screenshots

Changelog

1.7.1

  • Translation: Danish wording corrected for deleting a single log entry.
  • Maintenance: Two formatting errors from 1.7.0 fixed. They had no effect on how the plugin works.
  • Development: The automated tests run faster and need nothing but Docker.

1.7.0

  • Redesign: The settings page is reorganised around how you set it up. “Ko-fi connection” walks through the three steps in Ko-fi’s own order (copy the webhook URL, paste the token, press Send test) and shows whether Ko-fi’s requests are arriving and being accepted.
  • Feature: Tiers Ko-fi has sent that aren’t mapped to a role are listed, and can be added with one click.
  • Feature: A new Members tab lists everyone who has or had a membership through Ko-fi, with their role, status, member-since date, last payment and when access ends. It can show only active members, those ending within a week, or those that ended.
  • Logs: The request log can show only refused requests, says in words why a request was refused, shows times in the site’s time zone, links to the member’s profile, and shows each request’s payload. Paging no longer prints a button for every page.
  • Logs: Deleting a log now says which log it empties and leaves the other one alone.
  • Accessibility: Every checkbox and button has a label, and the copy button confirms in place instead of with a pop-up.
  • Fix: The descriptions of “Subscriptions only” and tier matching were inaccurate; they now say what the settings do.
  • Security: The log viewer no longer runs on AJAX endpoints, so the many low-privilege accounts this plugin creates have nothing of it to call. Viewing and deleting logs still require an administrator.
  • Translation: Complete Danish translation of the new screens.

1.6.1

  • Fix: Unticking “Automatically Clear Logs” on the settings page and saving left it switched on, so old log entries kept being deleted. It now switches off.
  • Fix: Two settings labels (“Only assign roles to subscribers.” and the expiry description) were always shown in English. They are now translated.
  • Translation: Three Danish wordings improved.

1.6.0

  • Feature: Other plugins can now steer what a Ko-fi payment does. Filters can skip a payment, refuse to create an account (for example to keep a member who deleted their account from being re-created by their next payment), change or withhold the role, and adjust a new account. Actions report an account created, a role assigned or removed (with the reason: tier change or expiry), and a payment logged. Nothing changes on a site that uses none of them.
  • Security: A role chosen by a filter passes the same checks as one chosen in the settings, so administrator and roles with site-running powers can never be granted, and a filter cannot set a new account’s role or email address. Hooks never see the verification token.
  • Reliability: A broken callback in another plugin can no longer turn a payment into an error that Ko-fi keeps retrying: the plugin carries on without it and notes it in the debug log. A payment refused by a filter is answered as received.

1.5.0

  • Fix: A supporter who changed their email address on the site kept paying through Ko-fi under the old one, and the next payment created a second account while the real account’s role expired. The plugin now remembers the addresses a member used before, so payments keep reaching the same account. If an old address now belongs to someone else, it goes to them, and the user log notes it.
  • Feature: members_for_kofi_supports_email_change() lets other plugins, such as an account page, check that changing the email address is safe.
  • Privacy: Previous email addresses, and the log entries recorded under them, are included in Export Personal Data and Erase Personal Data. They are kept while a membership is live, because they link its payments, and removed when it ends or the plugin is uninstalled.

1.4.0

  • Feature: Other plugins and themes can now read a supporter’s membership with members_for_kofi_get_membership(): whether it is active, the role, when it expires or ended, the last payment, and links and wording for managing or cancelling it on Ko-fi. Memberships that have ended are still reported, so an account page can say when.
  • Feature: The plugin now records when someone first became a member. The date stays the same through renewals, and through a lapse and a later return. For memberships that began before this version, the date can be filled in with WP-CLI: wp members-for-kofi member-since set <user-id> <date>.
  • Feature: Complete Danish translation. The plugin’s own bundled translations are now loaded; before, only language packs from translate.wordpress.org were.
  • Privacy: Membership dates are included in WordPress’s Export Personal Data tool. Erase Personal Data removes the record of a membership that has ended, and keeps a live one so the supporter does not lose what they paid for.
  • Change: Webhooks now accept only the hashed verification token introduced in 1.2.0. Sites updating from an older version are still converted automatically. Only a site whose settings were restored from a backup made before 1.2.0 is affected: Ko-fi payments are refused until you save the plugin’s settings page once (or enter the token again).

1.3.1

  • Fix: Updating to 1.3.0 could make a site very slow or unresponsive. A one-time clean-up of supporter accounts used a database query that could take many minutes, and it was started again by every visitor until it finished. The clean-up now takes a fraction of a second, and only one visitor’s request ever runs an update at a time, so the rest of the site keeps working.
  • If your site was affected, this update finishes the clean-up that 1.3.0 could not.

1.3.0

  • Security: New supporter accounts no longer receive the site’s “New User Default Role”. On a site where that setting was something powerful (even Administrator), every supporter used to get it.
  • Security: Roles with administrator-level powers can no longer be assigned to supporters, whatever they are called.
  • Privacy: Supporters’ email addresses are no longer used as their username or public name, where some themes showed them on a public author page. New accounts get a neutral username and the supporter’s Ko-fi name (if they supported publicly) or “Supporter”. Existing accounts created by the plugin are updated automatically; supporters still sign in with their email address.
  • Privacy: The plugin’s logs are now included in WordPress’s Export Personal Data and Erase Personal Data tools, and suggested text has been added to the privacy policy guide. Shipping addresses from shop orders are no longer stored.
  • Fix: The webhook now works on sites using plain permalinks, where Ko-fi payments could be lost without any error, and on multisite sub-sites. The settings page shows the right webhook address for your site.
  • Fix: Two payments arriving at the same moment from a new supporter no longer create duplicate accounts, and a payment Ko-fi delivers twice is only processed once.
  • Fix: Roles you gave someone yourself are no longer removed when their Ko-fi membership expires or their tier changes.
  • Change: Ko-fi shop orders and commissions no longer grant membership; only donations and subscriptions do.
  • Change: Ko-fi’s “Send test” button no longer creates an account. If an earlier test left one behind, you will see a notice pointing to it so you can delete it.
  • Settings: A warning appears if scheduled tasks (role expiry and log cleanup) are not running, and Ko-fi tier names that have no role mapping are noted in the log.

1.2.0

  • Security: The Ko-fi verification token is no longer stored in readable form. Only a one-way hash (SHA-256) of it is kept, so a database backup or export no longer reveals it.
  • Existing sites are converted automatically on the first visit or Ko-fi payment after updating. Your webhook keeps working and there is nothing to re-enter.
  • Settings: The token field is now write-only. It shows whether a token is saved, plus a short fingerprint you can compare between sites (for example staging and production). Leaving the field blank keeps the saved token; paste a new token to replace it.
  • Settings: If two different tokens are ever found stored at once, administrators see a warning asking them to re-enter the token.
  • Logs: A rejected webhook now says in the Request log whether no token was set up or the token did not match. Ko-fi itself is still only told “Unauthorized”.
  • Fix: The settings page now shows its messages. Before, a save that was refused (for example a missing token, or mapping a tier to the administrator role) was silently ignored, and a successful save showed no confirmation.
  • Important: After updating, going back to an older version of the plugin will stop webhooks from being accepted until you enter your Ko-fi verification token again in the settings.

1.1.0

  • Feature: Added automatic log cleanup with configurable retention period.
  • Feature: Reorganized admin settings page with separate sections for Ko-fi Settings, Role Assignment, and Logging.
  • Feature: Added support for viewing webhook request logs in addition to user logs.
  • Enhancement: Renamed “User Logs” tab to “Logs” with dropdown to switch between User and Request logs.
  • Enhancement: Renamed “General” tab to “Settings” for better clarity.
  • Enhancement: Added daily cron job to automatically delete old logs based on retention settings.
  • Enhancement: Settings now include “Automatically Clear Logs” (default: enabled) and “Number of Days to Keep Logs” (default: 30 days).
  • Improvement: Better organization of settings with clear section headers.
  • Fix: The request log table is now created when the plugin is updated, not only when it is first activated. Without this, updating from 1.0.x would have left the new Request log permanently empty.
  • Fix: Donation messages containing quotes, backslashes or accented characters are no longer mangled, and are stored exactly as they were sent.
  • Fix: Log cleanup now actually deletes old entries. It previously compared dates in two different formats and removed nothing.
  • Fix: When a supporter changes tier, the role from their previous tier is now removed instead of being left in place.
  • Fix: The log viewer no longer errors when an unexpected “rows per page” value is used.
  • Fix: A role that no longer exists on the site is no longer assigned to a supporter.
  • Fix: The “Enable Expiry” setting is now respected. Turning it off previously had no effect, and roles were still removed after the configured number of days.
  • Fix: Searching the Request log now searches the request log. It previously returned results from the User log instead, whichever tab you were on.
  • Security: The Ko-fi verification token is never stored in the request log, and is removed from the stored request details.
  • Security: The verification token is no longer written to PHP error logs.
  • Security: The webhook address now accepts only the request type Ko-fi actually sends, and ignores an address that keeps failing, so it cannot be used to fill your database. Genuine donations are never affected.
  • Security: Tokens are compared in a way that does not reveal how much of a guess was correct.
  • Improvement: Automated tests now run against a fresh install of the latest WordPress, including tests that send real donation requests over HTTP.

1.0.1

  • Build: Adjusted release packaging to exclude dev dependencies and include only production-ready vendor autoloader.
  • No functional code changes for end users.

1.0.0

  • Initial release.
  • Support for Ko-fi webhooks.
  • Automatic role assignment based on donations or memberships tiers.
  • Logging of user actions in database.