Developer hooks reference

GiveFlow provides extension hooks that let developers build add-ons and customize plugin behavior. This reference covers the main extension points, what they do, and example use cases.

All hooks use dot-notation namespacing (for example, giveflow.form.steps). Every hook below is a filter, so you attach to it with WordPress’s add_filter function, except giveflow.editor.assets, which is an action and uses add_action.

Admin hooks

giveflow.admin.pages

Register custom admin pages in the GiveFlow menu. Use this hook to add your own settings pages, reports, or tools to the GiveFlow admin area.

Example use cases:

Add a custom analytics dashboard
Create a donor import tool page

giveflow.editor.assets

An action, not a filter. It fires while GiveFlow is loading the form builder and passes the editor’s script handle, so you can enqueue your own JavaScript or CSS alongside it. Attach with add_action and enqueue in the callback. Nothing is returned.

Example use cases:

Register custom block editor sidebar panels
Add editor-specific stylesheets

Settings hooks

giveflow.settings.groups

Register a settings group of your own. Each group maps to a WordPress option with its own set of defaults, and GiveFlow’s settings REST routes then read and write it alongside the built-in groups.

Example use cases:

Add configuration options for a custom integration
Give an extension its own option with validated defaults

Campaign hooks

giveflow.campaign.types

Register custom campaign types beyond the built-in Standard type. The filter receives a map of type key to label, and the key you add becomes a valid campaign_type for new campaigns. An existing standard campaign can be converted to a registered type once; after that its type is fixed.

Example use cases:

Add a campaign type with its own page template
Add a campaign type with its own validation rules

giveflow.campaign.starter_blocks

Change the block markup GiveFlow writes into a campaign page when the campaign is created. The filter receives the default markup and the campaign, and returns the markup to use.

Example use cases:

Seed a different layout for a campaign type you registered
Add your own blocks above the donation form on every new campaign page

Form hooks

giveflow.form.config

Modify the donation form configuration before it renders. Use this hook to alter form settings, add custom data, or change form behavior dynamically.

Example use cases:

Inject custom configuration based on the current page
Override form settings for specific campaigns

giveflow.form.steps

Change the sections GiveFlow builds from the form’s blocks before the runtime renders them. Each entry is one section, such as the amount chooser, a group of donor fields, or the submit button, and carries the page it sits on when the form is multi-step. It receives the sections, the form, the variant, and the visitor context.

Example use cases:

Add a section of your own ahead of the submit button
Drop a section for one form variant

giveflow.form.amounts

Modify the suggested donation amounts displayed on the form. Use this hook to change amount options dynamically based on context. It receives four arguments: the normalized presets, the form, the variant, and the visitor context. Each preset is an array with cents, impact and preselected keys.

Example use cases:

Show different amounts for different campaigns
Adjust amounts based on the donor’s country

giveflow.form.visitor_context

Add to the context GiveFlow builds for the current visitor. By default it holds the locale, a country (empty unless you fill it in) and the logged-in user id, and it is passed to gateway resolution and to the other form filters.

Example use cases:

Set the visitor’s country so the gateway options suit where they are
Add data your own form filters need

giveflow.form.variant

Control which form variant is displayed. Use this hook to implement A/B testing or conditional form rendering.

Example use cases:

Show different form layouts based on traffic source
Run A/B tests on form designs

Receipt hooks

giveflow.receipt.renderers

Register additional receipt renderers. A renderer implements GiveFlow’s ReceiptRenderer interface: it decides which donations it applies to, carries its own numbering scope, and returns the receipt as PDF bytes. Every renderer that applies to a donation runs, alongside the built-in one.

Example use cases:

Add a custom-branded PDF receipt template
Create a receipt format for a specific country’s tax requirements

Portal hooks

giveflow.portal.url

Override the donor portal URL. The filter receives an empty string, and returning a non-empty URL replaces the address GiveFlow would otherwise use, which is the permalink of the Donor portal page it provisioned. Use this hook if you host the portal somewhere else.

Example use cases:

Change the portal URL for a multilingual site
Point to a custom portal implementation

Spam hooks

giveflow.spam.min_amount_cents

Adjust the minimum donation amount, in cents. The default is 100 cents, so 1.00 in your base currency. Use this hook to raise or lower the minimum.

Example use cases:

Set a higher minimum to reduce card-testing attacks
Lower the minimum for a specific micro-donation campaign

Usage example

Here is a basic example of using a GiveFlow hook in your plugin or theme:

add_filter('giveflow.form.amounts', function (array $presets, $form, $variant, $visitor) {
    // Double the suggested amounts on one form
    if ($form->slug === 'major-appeal') {
        foreach ($presets as &$preset) {
            $preset['cents'] *= 2;
        }
        unset($preset);
    }

    return $presets;
}, 10, 4);

Declare the argument count you accept, as the fourth argument to add_filter. WordPress passes one argument otherwise, and $form would be missing.