Zeffy Campaign Contributors self-updates

Display contributor data for a single Zeffy campaign on a protected WordPress page. This plugin is not sanctioned or approved by Zeffy. I wrote it because I had a need. I do hope Zeffy might fork it an make a better version, because I am a well known idiot.

This plugin connects to the Zeffy API, pulls payment data for one configured campaign, and renders a frontend table through a shortcode. It also includes a simple login/register gate so visitors can create an account and view the report if they are assigned the correct role.

Features

• Pulls payment data from the Zeffy API for one campaign
• Displays contributor data with a shortcode
• Lets admins choose which columns appear on the frontend
• Supports a configurable Only Show Payments After date filter
• Discovers rate_id values from the campaign's payment history
• Lets admins map rate_id values to human-friendly rate titles
• Creates a zeffy WordPress role for frontend access
• Checks GitHub releases for plugin updates

Requirements

• WordPress 6.0+
• PHP 7.4+
• A Zeffy organization API key

Installation

Option 1: Install from a GitHub release

1. Download the latest plugin .zip from the GitHub releases page.
2. In WordPress admin, go to Plugins -> Add New -> Upload Plugin.
3. Upload the .zip file and activate the plugin.

Option 2: Install manually

1. Copy this plugin into your WordPress wp-content/plugins/ directory.
2. Make sure the main plugin file is zeffy-campaign-contributors.php.
3. Activate the plugin from the WordPress admin.

What Happens on Activation

When the plugin is activated, it creates a WordPress role named zeffy with basic read access. New accounts created through the plugin's frontend registration form are assigned this role automatically.

For backward compatibility, the plugin also still recognizes the legacy pool role if it already exists, but it does not create or assign that role anymore. This plugin was originally create for a public pool sponsored by a nonprofit

Configuration

After activation, go to:

Settings -> Zeffy Contributors

You will see these settings:

• Zeffy API Key Enter your organization API key from Zeffy.

• Campaign Name Enter the exact campaign title as it appears in Zeffy.

• Only Show Payments After Optional date in YYYY-MM-DD format. If set, only succeeded payments created on or after this date are shown on the frontend report.

• Rate Titles The plugin discovers rate_id values from the campaign's payment history and lists each discovered rate with:

  • Rate ID
  • Amount
  • Rate Title We do this because as of 2026.05.12 the Zeffy API did not expose rate_title

  If you enter a title for a given rate_id, the frontend report will display that title instead of the raw rate_id.

• Exposed Fields Choose which columns appear on the protected frontend table.

Usage

Create or edit a WordPress page and add this shortcode:

[zeffy_campaign_contributors]

Important access note

By default, this shortcode page includes a self-registration form. Any visitor who registers through that form is assigned the zeffy role and can then view the report.

If you need invitation-only access, manual approval, or tighter membership control, you should customize this behavior before using the plugin on a public site.

Frontend behavior

• If the visitor is not logged in, the shortcode shows a login/register form.

• If the visitor registers through this form, they receive the zeffy role.

• Logged-in users with one of these roles can view the report:

  • zeffy
  • administrator
  • admin
  • legacy pool

• Logged-in users without access see a permission warning.

How Rate Titles Work

Zeffy exposes rate_id on payment items, but does not expose a friendly rate title in the API response the plugin uses.

To make the report readable:

1. The plugin scans the campaign's payment history and discovers all seen rate_id values.
2. The admin can assign a custom Rate Title to each one.
3. On the frontend:
   • if a title exists, the plugin shows the title
   • if no title exists, the plugin shows the raw rate_id

Data Rules

• The frontend contributor report uses only succeeded payments.
• The optional Only Show Payments After date applies only to the frontend report.
• Rate discovery is broader and uses the campaign's payment history so admins can map old and new rates.
• API responses are cached for a short period to reduce repeated requests. By default, the cache TTL is 5 minutes.

Updates

This plugin is configured to check GitHub releases from:

fishdan-plugins/ZeffyCampaignReporter

If a newer release is available and includes the plugin zip asset, WordPress should offer the update through the normal plugins screen.

Important note

The built-in updater expects GitHub releases to be public. If you make the repository private, the updater will need additional authentication logic.

Release Workflow

This repository includes a GitHub Actions workflow that runs on every push to main.

The workflow:

1. bumps the plugin version
2. commits the version bump
3. tags the release
4. builds the plugin zip
5. publishes a GitHub release

That release zip is what the plugin uses for update checks.

Available Filters

The plugin exposes several WordPress filters for customization:

• zeffy_campaign_contributors_can_view
• zeffy_campaign_contributors_available_columns
• zeffy_campaign_contributors_columns
• zeffy_campaign_contributors_row
• zeffy_campaign_contributors_cache_ttl

Troubleshooting

No contributor data appears

Check the following:

• the Zeffy API key is valid
• the campaign name matches the Zeffy campaign title exactly
• the campaign actually has succeeded payments
• Only Show Payments After is not filtering everything out

Rate titles table is empty

This usually means one of the following:

• the API key is missing or invalid
• the campaign name does not match
• the campaign has no payments yet

Updates are not showing in WordPress

Check the following:

• a GitHub release exists
• the release has a plugin .zip attached
• the release tag matches the plugin version format, such as v0.1.1
• the repository is public

Notes

• This plugin is designed around a single configured Zeffy campaign per WordPress site.
• The frontend report is intentionally protected behind login and role checks.
• The plugin currently includes a self-registration flow on the protected page.