“Prefill for Donations Forms” is a new ability starting in Charitable Pro 1.8.13 that lets you pre-populate donation form fields using URL parameters. When a donor opens a donation page with the right query string, fields such as name, email, address, and custom form fields (text, radio, checkbox, select, address) can be filled in automatically. This is useful for email campaigns, landing pages, or links from external systems where you want to pass donor or context data into the form.

Table of Contents

Requirements

• Charitable Pro: Version 1.8.13 or higher
• WordPress: Version 6.2 or higher
• PHP: Version 7.4 or higher

URL prefill must be enabled per campaign (see below). It works with both the standard donation form and the Visual Form Builder(custom fields, address fields, radio, checkbox, select).

Enabling URL Prefill

1. Edit the campaign whose donation form you want to prefill.
2. Open the Campaign Builder (or the form/settings area where the donation form is configured).
3. Find the Enable URL Prefill toggle (in the form display options, near Enable Visual Form).
4. Turn Enable URL Prefill on and save the campaign.

If URL prefill is disabled for the campaign, query parameters are ignored and no fields are pre-populated. When enabled, only parameters that match allowed field keys and pass sanitization are used.

Parameter Format

• Prefix: By default, all prefill parameters must use the cf_ prefix.
  Example: ?cf_first_name=Jane&cf_last_name=Doe
• Field key: After the prefix, the parameter name must match the form field key (e.g. first_name, last_name, email, or custom field keys such as field_7 for Visual Form fields).
• Value: The value is sanitized according to the field type (text, email, URL, textarea, etc.). Values that fail sanitization or exceed the maximum length are discarded.

Example URL:

https://yoursite.com/campaigns/my-campaign/?cf_first_name=Jane&cf_last_name=Doe&[email protected]

Optional: You can remove the cf_ prefix requirement using the filter charitable_prefill_use_prefix (see Developer Resources). In that case, parameters like ?first_name=Jane would be read. Using the prefix is recommended to avoid clashes with other plugins or WordPress query vars.

Supported Field Types

Prefill is supported for the field types below, and only these. A field type that is not listed ignores the parameter.

• Text fields – Single-line text (sanitized as text).
• Hidden – Carries a value you supply rather than one the donor types. Addressed by its Field Name rather than a field ID, so a hidden field named source is filled by ?cf_source=. Requires Charitable Pro 1.8.18 or higher.
• Radio – One option value; the URL value must match an option value to select it.
• Checkbox – One or more option values. Use a comma-separated list in a single parameter to pre-check multiple options (e.g. cf_my_checkbox=opt1,opt2).
• Select – Single option value (or the selected value for single-select dropdowns). For multi-select, same comma-separated behavior as checkbox where applicable.
• Address fields – Subfields are supported with keys: address, address_2, city, state, postcode, country.
  Example: ?cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Additional behavior:

• Email – Parameter names containing email (e.g. user_email, email) are sanitized with sanitize_email().
• URL / website – Keys such as url, website, or containing _url are sanitized with esc_url_raw().
• Textarea-style fields – Keys such as message, comment, notes, description, special_message use sanitize_textarea_field().

Fields that are never prefilled (security) include: campaign_id, donation_amount, amount, gateway, password, payment and nonce fields, and other sensitive or internal keys. The full list can be extended or modified by developers (see Developer Resources).

Parameter Names and Examples

Common donor fields

Parameter	Description	Example value
cf_first_name	Donor first name	Jane
cf_last_name	Donor last name	Doe
cf_user_email	Donor email	[email protected]
cf_email	Alternative email key (if form uses it)	[email protected]

Address fields

Parameter	Description	Example value
cf_address	Address line 1	123 Main St
cf_address_2	Address line 2	Apt 4
cf_city	City	Boston
cf_state	State/region	MA
cf_postcode	Postcode/ZIP	02101
cf_country	Country code	US

Visual Form custom fields

• Custom fields in the Visual Form Builder use internal keys like field_7 (where 7 is the field ID). Use the same key with the cf_ prefix.
  Example: ?cf_field_7=My+value
• In some contexts the numeric ID is also accepted (e.g. cf_7 may map to field_7). Prefer cf_field_N for clarity when documented by your form.
• Hidden fields are the exception. A hidden field is addressed by the Field Name you typed in the builder, not by a field ID. A field named source is filled by ?cf_source=spring-appeal. The same name is used for the form input, the parameter, and the key the value is stored under after the donation, so there is only one name to remember. Full URLs are accepted, so you can pass a whole referring address rather than a slug.

Radio and select

• Use the exact option value that appears in the form.
  Example: for a “Country” select with value US, use ?cf_country=US.

Checkbox (multiple)

• Use one parameter with comma-separated option values.
  Example: for a checkbox field with options newsletter and updates, use ?cf_interests=newsletter,updates(replace interests with your field key).

Full example URL

https://yoursite.com/donate/?cf_first_name=Jane&cf_last_name=Doe&cf_user_email=jane%40example.com&cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Use proper URL encoding (e.g. %20 for space, %40 for @ in email).

Security and Limits

• Blocked keys: Sensitive and internal keys (e.g. donation_amount, gateway, password, nonces) are never read from the URL. Donation amount and payment method cannot be prefilled via query string.
• Max parameters: The number of prefill parameters read from the URL is limited (default 20). This can be changed with the filter charitable_prefill_max_params.
• Max length: Each value is truncated to a maximum length (default 500 characters). This can be changed with the filter charitable_prefill_max_value_length.
• Sanitization: All values are sanitized by field type (text, email, URL, textarea). Invalid or empty results after sanitization are not applied.
• Per campaign: Prefill only runs when Enable URL Prefill is on for that campaign. No prefill is applied on campaigns that have it disabled.

Where to Find the Value Afterwards

A prefilled value is saved with the donation. There are three places to read it back.

1. The donation details screen. Open the donation in Charitable > Donations and look at the summary panel on the right. The field appears under its label with the captured value.
2. The donation CSV export. In Charitable > Donations, open the Export panel and the field appears under Custom Fields from Visual Forms. Once its export option is on, the value arrives as its own column headed with the field’s label.
3. Directly, for developers. The value is stored as post meta on the donation under the field’s own name with no prefix, so a field named source becomes post meta source.

Choosing where it appears

Each field’s Advanced Options section in the Campaign Builder controls this.

Option	What it does	Default for a hidden field
Enable in Export	Adds a column to the donation CSV export	On
Enable in Donation Meta	Shows the value on the donation details screen	On
Enable Email Tags	Creates an email tag for use in email templates	Off
Send in Automation Webhooks	Includes the field in Automation Connect payloads	Off

Both defaults are on for a hidden field, because a field whose purpose is carrying information onward is not much use if the information cannot be read back.

A hidden field created before Charitable Pro 1.8.18 is the exception. Earlier versions had no control for this and stored an “off” setting for every hidden field, so Charitable treats that as your preference rather than overriding it. To start exporting one of those fields, open it in the Campaign Builder, expand Advanced Options, and turn on Enable in Export. Hidden fields added from 1.8.18 onward export by default.

A field that captured nothing

A field that captured no value writes no row at all, rather than an empty one. If you expect a value and find the field missing from the donation entirely, the value did not arrive. Check the campaign’s URL prefill toggle first, then that the parameter name matches the field name exactly.

Recording the referring page automatically

If you want the referring page recorded without adding a parameter to every link, put the {referrer} merge tag in a hidden field’s Field Value instead of using a URL parameter. Charitable fills this in the browser, from the page the donor arrived from.

Filling it in the browser rather than on the server is what makes it safe on a cached site. A value worked out on the server is stored in your page cache along with the rest of the page, so every donor after the first would be recorded as having come from wherever the first one did. Because the browser fills it, it also works inside a donation modal. Nothing is recorded for a visitor with JavaScript turned off, which is deliberate: a blank is more useful than a confidently wrong answer about where a gift came from.

Troubleshooting

Fields are not prefilling

• Confirm Enable URL Prefill is turned on for the campaign (Campaign Builder → form options).
• Check that the URL uses the cf_ prefix (e.g. cf_first_name, not first_name) unless you have disabled the prefix via filter.
• Ensure the parameter name matches the field key (e.g. user_email or email for the email field, field_7 for a custom field with ID 7).
• For select/radio/checkbox, the value must exactly match an option value in the form.

Value is cut off or empty

• Values are truncated to the max length (default 500 characters). Use the charitable_prefill_max_value_length filter if you need longer values.
• If the value is empty after sanitization (e.g. invalid email), it will not be applied. Check encoding (e.g. %40 for @ in emails).

Address subfields not filling

• Use the exact keys: address, address_2, city, state, postcode, country. They are prefixed like other params: cf_address, cf_city, etc.
• Ensure the campaign’s form actually includes address fields and that URL prefill is enabled for the campaign.

Custom Visual Form fields

• Use the key format field_N (e.g. cf_field_7) where N is the custom field ID. Check the form builder or inspect the form’s name attributes to confirm IDs.

Developer Resources

Filters

• charitableprefilluse_prefix – apply_filters( 'charitable_prefill_use_prefix', true )
  Return false to allow parameters without the cf_ prefix (e.g. ?first_name=Jane). Default true.
• charitableprefillenabled – apply_filters( 'charitable_prefill_enabled', $enabled, $campaign_id )
  Override whether URL prefill is enabled for a campaign. Return true or false; return null to use the campaign’s saved setting.
• charitableprefillmax_params – apply_filters( 'charitable_prefill_max_params', 20 )
  Maximum number of URL parameters to read for prefill. Default 20.
• charitableprefillmaxvaluelength – apply_filters( 'charitable_prefill_max_value_length', 500, $field_key )
  Maximum character length per value. Default 500.
• charitableprefillblocked_keys – apply_filters( 'charitable_prefill_blocked_keys', $blocked_keys )
  Add or remove keys that must never be prefilled from the URL (e.g. security-sensitive field names).
• charitableprefillsanitize_value – apply_filters( 'charitable_prefill_sanitize_value', $sanitized, $field_key, $value )
  Modify the sanitized value before it is applied to the field.

Class and methods

• CharitableFormPrefill::get_instance() – Returns the singleton instance.
• getprefillvalues( $campaign_id ) – Returns an array of all parsed prefill values (field_key => value) for the current request and campaign.
• getvalue( $key, $campaignid ) – Returns the prefill value for a single field key, or null if not set. Handles field_N / numeric key mapping for Visual Form custom fields.
• isenabledforcampaign( $campaignid ) – Returns whether URL prefill is enabled for the given campaign.
• hasprefillparams() – Returns whether the current request has any prefill parameters in the URL (useful for early bailout).
• reset() – Clears the cached parsed values (e.g. for testing).

Version history

Version	Changes
1.8.13	URL Query String Prefill for donation form fields (text, radio, checkbox, select, address). cf_ prefix, per-campaign toggle, sanitization by field type, blocked keys, and filters.
1.8.18	Hidden fields can be prefilled, addressed by their Field Name. Captured values are now shown on the donation details screen and can be included as a donation CSV export column, controlled per field in Advanced Options. Adds the {referrer} merge tag for hidden fields.

---

For building the donation form and custom fields, see the Visual Form Builder and donation form documentation.