“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:

• Text fields – Single-line text (sanitized as text).
• 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.

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.

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.

---

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