Prepopulating one-time custom donation amount field and other values through a URL parameter

created

With Soapbox Donations, you can populate several fields on the donation form, including the one-time custom amount field, by passing one or multiple values to the form through a URL.

What is more, within the Soapbox Donation edit view, you can choose to select the one-time 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 Soapbox 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:

  • 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 dropd down, you can view the source of the Donations page and check the values of the Campaign picklist options.
    Example: sfcampaign=7013D0000005k9EQAQ

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?onetime_other_amt=25

To included multiple parameters in the URL, include a & between each:

https://www.yoururl.com/donate?onetime_other_amt=25&name=Mickey%20Mouse&company=Disney

Setting the one-time custom amount field to be Selected by Default or Read Only

In order to set the Custom Amount Field for One-Time Payments as the default or as read only for a form:

Best practices for populating the one-time custom amount field

If you wish to set the one-time custom amount field through a URL parameter, make sure that the Soapbox Donation form in question has the One-Time 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 one-time amount via a URL parameter, display ONLY the One-Time Payment Custom Amount Field on the Soapbox Donation form and display no Predefined Amounts for One-Time Payment nor any options for Recurring Payments.

The end result will display only the One-Time Payment 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:

screenshot-donation-only-custom.png

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.

Have more questions? Submit a request
Article is closed for comments.