Giving Forms and URL Parameters

Dynamically populate your Giving Form.

URL parameters are a great way to personalize the content displayed on a web page, or, in this case, a Giving Form.

For example, say you have a donor accessing one of your organization's pages that is geared toward a demographic in Pennsylvania.  By including a URL parameter in the link to the Giving Form, the Giving Form would then show Pennsylvania as the selected State, instead of requiring the donor to select a state.

Example of URL Parameters

The following would pre-populate a Giving Form with:

  • State: New York
  • City: New York
https://www.example.com/giving-form?state=NY&city=New%20York

The basics of it are that you begin the parameter statement with a at the end of the URL, i.e. the page name, then separate each subsequent parameter with an &.

Available Parameters

Important: Characters such as blank space, periods, and other punctuation will not be read by the URL parser unless formatted in a specific way.  For example, white space becomes %20, and a period becomes %2E.  For a full list of UTF-8 encoding, please refer to this helpful article from W3Schools.

Parameter Name Parameter Example
First Name first_name Ernest
Last Name last_name Hemingway
Middle Initial middle_initial Herbert
Address Line 1 address1 10201%20Arrollo%20Lane
Address Line 2 address2 Unit%208B
City city Memphis
State state TX
Postal Code zip_code 75208
Country country US
Company Name company_name Macromedia

Phone Number

phone 2146024412

Email Address

email jtree%40gmail%2Ecom

Frequency

frequency (See Advanced Parameters)

Frequency Options

frequency_options (See Advanced Parameters)

Gift Arrays

gift_arrays (See Advanced Parameters)

Payment Type

payment_type credit

Gift Amount

gift_amount 299

Designation (Singular)

designation 2736a9f5-0155-4096-a16b-0366a37bdd44

Designations (Multiple)

designations (See Advanced Parameters)

Cash Default Amount
(Overrides Gift Amount)

cash_default 250

UTM Term

utm_term randomWord

UTM Campaign

utm_campaign String

UTM Medium

utm_medium String

UTM Content

utm_content someOtherWord

UTM Source

utm_source youDefineThisOne

Reference Code

reference_code youDefineThisOneToo

Corporate Matched Employer

corporate_match_employer (See Advanced Parameters)

Custom Field Default

(See Advanced Parameters) (See Advanced Parameters

Start Date

start_date 2024-06-01

End Date

end_date 2024-06-01

End Count

end_count 3

Anonymous

anonymous anonymous

Advanced Parameters

Most of the parameters listed above do not require much formatting.  However, there are a few that require some specific formatting.

Before we begin, something that will save you a lot of time configuring these parameters is this super-useful Chrome console command:

encodeURIComponent('your unformatted parameter goes here');

This will return a valid URL parameter.  For example, the above command would output this:

your%20unformatted%20parameter%20goes%20here

Now then, on to the fun stuff.

Frequency and Frequency Options

These are the allowed values for the Frequency (or Frequency Options) of the gift:

  • "Once"
  • "Weekly"
  • "1st and 15th"
  • "Every 2 Weeks"
  • "Monthly"
  • "Quarterly"
  • "Semi-Annually"
  • "Annually"

Unformatted, the Frequency Options parameter would appear as an array of Strings:

frequency_options=["once","monthly","annually"]

That, when formatted, reads as follows:

frequency_options=%5B%22once%22%2C%22monthly%22%2C%22annually%22%5D

For single frequency, a URL parameter would read as follows:

frequency=monthly

Gift Arrays

Unformatted/Non-Encoded:

gift_arrays=[11,12]

Formatted/Encoded:

gift_arrays=%5B11%2C12%5D

Designations (Multiple)

Unformatted/Non-Encoded:

designations=[ 
{"id": "2736a9f5-0255-a196-a36b-0366637bdd44", "amount": 10},
{"id": "d61bf66b-7c01-d566-bf0e-058ac5cb0afa", "amount": 15}
]

Formatted/Encoded (some scrolling required):

designations=[{"id"%3A"2736a9f5-0255-a196-a36b-0366637bdd44"%2C"amount"%3A10}%2C{"id"%3A"d61bf66b-7c01-d566-bf0e-058ac5cb0afa"%2C"amount"%3A15}]

Customer Meta

Non-Encoded, as a JSON object:

customer_meta = { 
"META_1": "meta-value-here",
"META_2": "the-other-meta-value",
"META-4": "where did meta 3 go?"
}

To properly encode this parameter, you must use a different method than described above:

var yourCustomerMeta = encodeURIComponent(
JSON.stringify(
       customer_meta = {
      "META_1": "meta-value-here",
           "META_2": "the-other-meta-value",
           "META-4": "where did meta 3 go?"
       }
)
);

Which will then result in an encoded value:

'%7B%22META_1%22%3A%22meta-value-here%22%2C%22META_2%22%3A%22the-other-meta-value%22%2C%22META-4%22%3A%22where%20did%20meta%203%20go%3F%22%7D'

Corporate Matched Employer

This is a Unique ID sourced from Double the Donation that corresponds with the company that will match the gift being made.

Custom Field Default Value

This parameter will set the default value for a Custom Field.  For a Text Input Custom Field, the value can be whatever you want, but for selection Custom Fields, e.g. Drop-down, Multiple Choice, the value must be included in the list.

Example

Say we have a drop-down Custom Field named "Dropdown Test Eight", and it has a value we want to select, named "Option D".  You would set this parameter like so:

[your-page-url]?Dropdown%20Test%20Eight*=Option%20D

Notice the required asterisk after the name of the Custom Field.