URL Parameters and Data Tags

When customizing or pre-filling your iDonate Giving Form, there are two main ways to pass information into the form: URL parameters and data tags. While both can send data to your form, they work in different ways and serve different purposes.

Understanding URL Parameters vs. Data Tags

URL Parameters

URL parameters are pieces of information added to the end of a webpage’s address to pass data into a Giving Form as the page loads. They start with a question mark (?) and include one or more key-value pairs, separated by ampersands (&).

For example, the URL below shows how to pre-populate a Giving Form with New York as the state and New York as the city in their respective address fields.

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

When to use:

Use URL parameters to dynamically pre-populate form fields. This approach is ideal when directing donors from an email or campaign link containing their information.

Data Tags

Data tags are attributes you include directly in HTML where your Giving Form is embedded. They pass configuration data to the form’s script before it loads, allowing you to control how the form behaves or what it displays.

<div id="idonate-giving-form-container"
  data-embed-id="fda18304-63b9-46fb-bccd-e230656c7195"
  data-frequency="monthly"
  data-gift_amount="234">
</div>
<script src="https://apps.idonate.com/idonate-giving-form.js"></script>

In this example:

• data-embed-id tells the script which Giving Form to load.
  • Automatically provided by iDonate.
• data-frequency sets the Giving Form to recurring monthly donations.
• data-gift_amount presets the donation amount.

Naming Convention

All data attributes used in the Giving Form must begin with the prefix data-.

While both hyphenated and snake_case formats are supported (e.g. data-gift-amount vs. data-gift_amount), it is best practice to pick and stay with one format for consistency across implementations.

When to use:

Use data tags when embedding a Giving Form on your website and you want to control default values or settings at the page level, especially when the same form may appear on multiple pages with different purposes.

Available Parameters

Advanced Parameters

Most of the parameters listed above require little formatting, but a few have specific formatting requirements.

Before getting started, you can save a lot of time when configuring parameters by using this handy browser console command:

encodeURIComponent('your unformatted parameter goes here');

This command returns a properly formatted URL parameter. For example, running the command above would output:

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

To open browser developer tools use one of the following keyboard shortcuts and then click Console:

• Windows: F12 or Crtl + Shift + I
• Mac: Cmd + Option + I

Frequency and Frequency Options

The following are the supported values for the Frequency and Frequency Options of a gift:

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

URL Parameters

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

Data Tags

data-frequency_options='["once", "quarterly", "weekly"]'
data-frequency="once"

Note: When using this data tag, it’s recommended to also define a default frequency by including the data-frequency attribute, set to one of the available frequency options.

Gift Arrays

URL Parameters

Unformatted/Non-Encoded:

gift_arrays=[11,12]

Formatted/Encoded:

gift_arrays=%5B11%2C12%5D

Data Tags

data-gift-arrays="[5,10,15,20,25]"

Designations (Multiple)

URL Parameters

Unformatted/Non-Encoded:

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

Formatted/Encoded:

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

Data Tags

data-designations='[{"id": "046fa1c9-edaf-41d4-9708-ab45f977c8e5", "amount": 5.12}, {"id": "bb1148e3-229e-43e6-843a-28211e3f01ff", "amount": 7.68}]'

Customer Meta

URL Parameters

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 an additional method, JSON.stringify(), in the browser developer console than described above:

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'

Data Tag

data-customer-meta='{"some field": "12345", "i love metadata": "99 red balloons", "more custom data": "user never sees this but it gets posted", "another field": "this is another value"}'

Custom Field Default Value

This parameter will set the default value for a Custom Field that has already been created for a Giving Form in iDonate.

For text input fields (e.g., paragraph, short text, or internal metadata), the value can be any text you choose.

For selection fields (e.g., single choice or dropdown), the value must match one of the available user defined options during Giving Form creation/editing.

For date fields, the value must be a valid date, and for number fields (including currency), the value must be a valid number.

URL Parameters

If a dropdown Custom Field named "Dropdown Test Eight" includes a value "Option D", the parameter should be set as follows:

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

Data Tags

For data tags to work, each custom field must have a Name written in snake_case (e.g. shirt_size, favorite_color) during form creation in iDonate. This snake_case name is what you’ll use in the data- attribute. Below are examples for each custom field input type:

<div id="idonate-giving-form-container"
    data-embed-id="embed-UUID"
    data-paragraph-field*="Paragraph text goes here."
    data-short-text*="Short text goes here."
    data-internal-metadata*="Internal metadata text goes here."
    data-single-choice*="Choice 2"
    data-dropdown-field*="Choice 1"
    data-date-field*="2026-01-01"
    data-number-field*=33
    data-currency-field*=50
</div>
<script src="https://apps.idonate.com/idonate-giving-form.js"></script>

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.