Boost recurring donations this giving season with the new upsell prompt!With the Donations app, you can populate the donation amount and several fields on the donation form by passing one or multiple values to the form through a URL.
What is more, within the Donations app edit view, you can choose to select the one-time or recurring custom amount field by default or choose to make it read only and selected by default. Making it read only will set the value based on the URL parameter, select it by default, and not allow the end user to alter the value within the form.
Acceptable parameters
The following is a list of acceptable parameters which can be included in a URL for a Donations page. The %20 string referenced in various examples is the URL-encoded representation of a blank space, though blank spaces may be used as well:
- amt: Selects either a one-time or recurring predefined amount that matches the value in the parameter, depending on which frequency is showing and set as the default. If no predefined amount matches the value, it is entered into the custom amount field and the custom amount option is selected.
Example: amt=150 - onetime_other_amt: Populates value on one-time custom amount field, if it is present on the Soapbox Donation form. See "Best practices..." below for key considerations when using this parameter.
Example: onetime_other_amt=150 - name: Populates both the First Name and Last Name fields in the Contact Information section by splitting the value at the separating space. For
Example: name=Mickey%20Mouse
Also acceptable: name=Mickey Mouse - email: Populates the Email field in the Contact Information section
Example: email=mickey.mouse@example.com - phone: Populates the Phone field in the Contact Information section, if present
Example: phone=(202)%20555-1212
Also acceptable: phone=(202) 555-1212 - company: Populates the Company field in the Contact Information section, if present
Example: company=Disney - custom_input_one: Populates the Custom Field #1 field in the Contact Information section, if present
Example: custom_input_one=my%20custom%20field%20value
Also acceptable: custom_input_one=my custom field value - custom_input_two: Populates the Custom Field #2 field in the Contact Information section, if present
Example: custom_input_two=my%20custom%20field%20value
Also acceptable: custom_input_two=my custom field value - custom_input_three: Populates the Custom Field #3 field in the Contact Information section, if present
Example: custom_input_three=my%20custom%20field%20value
Also acceptable: custom_input_three=my custom field value - custom_input_four: Populates the Custom Field #4 field in the Contact Information section, if present
Example: custom_input_four=my%20custom%20field%20value
Also acceptable: custom_input_four=my custom field value - sfcampaign: Selects the value in the Campaign drop down that matches the 18-digit Campaign Id in Salesforce for the desired Campaign. If you are uncertain of the Campaign Id for a Campaign in the drop down, you can view the source of the Donations page and check the values of the Campaign picklist options.
Example: sfcampaign=7013D0000005k9EQAQ - For custom fields for Microsoft Dynamics or Salesforce included on the form, you may use the Element Name listed in the custom fields table of the Donation form followed by an equals sign and the desired value
Example: crm_elementname=my%20custom%20field%20value
Also acceptable: crm_elementname=my custom field value
Adding parameters to the URL
To add a parameter to the URL, simply include a ? at the end of your Soapbox Donation URL followed by the parameter, an equals sign and its value:
https://www.yoururl.com/donate?amt=25
To included multiple parameters in the URL, include a & between each:
https://www.yoururl.com/donate?amt=25&name=Mickey%20Mouse&company=Disney
Setting the one-time or recurring custom amount field to be Selected by Default or Read Only
In order to set the Custom Amount Field for One-Time Payments or Recurring Payments as the default or as read only for a form:
- Open the Soapbox Donation form you wish to edit
- Click the Payment tab
- Under One-Time Payments in the right column, choose Selected by Default or Read Only
- Under Recurring Payments in the right column, choose Selected by Default or Read Only
- Click Save
Best practices for populating the one-time custom amount field
If you wish to set the one-time or recurring custom amount field through a URL parameter, make sure that the Donation form in question has the One-Time Payment or Recurring Payment option set to Show or Selected by Default and that the Custom Amount Field is not hidden.
In addition, it is important to note that the behavior of the Soapbox Donation form removes the value in a custom amount field if the end user selects a different option. Therefore, for best results when setting the amount via a URL parameter, display ONLY the appropriate Custom Amount Field on the Soapbox Donation form and display no Predefined Amounts.
The end result will display only the Custom Amount Field prepopulated with the value set in the URL - and, if you have chosen Read Only for the Custom Amount Field, the end user won't be able to alter this value from within the form:
Common uses
This functionality is helpful if you send personalized mass emails with recipient-specific links to your donation page and wish the donation page to be prepopulated with their information.
In addition, you may use this feature in conjunction with the Forms app to easily create multi-step workflows for things such as membership applications requiring payment. To do so, you can make use of the Forms app ability to set custom redirects upon form submission that include variables specific to the user.
URL Parameter for Amount Overrides Default Amount for Donations Form
If a link to a Donation form includes a URL parameter that defines a default value, this default value in the URL parameter will override any default value set in the administrator. This allows you to personalize ask amounts in direct emails to constituents, regardless of whether or not a default value exists in the administrator for a Donation form.