JavaScript API
Use JavaScript methods to trigger donation forms and monitor supporter interactions across your website.
The Fundraise Up JavaScript API helps you create more personalized donation experiences and track supporter interactions across your website. This tool offers two methods:
- Open Checkout enables the Fundraise Up checkout to open based on different events or triggers, with prefilled parameters such as donation amounts or supporter information.
- Event Handler Registration enables you to track Fundraise Up conversion events in external applications and systems that aren't natively supported by our platform.
In the sections below, you'll find detailed information about each of these methods and their associated parameters.
Open Checkout method
Method: FundraiseUp.openCheckout
This method makes the Fundraise Up checkout open in response to various events or triggers on your website. It can open either the Checkout Modal or a Campaign Page. You can dynamically populate the checkout form with custom data based on user interactions on your website, such as scrolling to a specific point or finishing a video.
You can prefill fields such as supporter details, donation amount, currency, and more. By passing the necessary parameters when opening the checkout, you can create tailored scenarios and integrate them into complex interfaces:
- Set specific donation amounts for different campaign appeals.
- Prefill designation fields for targeted fundraising pages.
- Open checkout with monthly recurring plan selected when promoting sustainer programs.
- Trigger checkout when supporters complete key actions on your site.
Here's the basic syntax:
1FundraiseUp.openCheckout(campaignId: string, options?: FundraiseUpOpenCheckoutOptions)
This method works immediately without waiting for Fundraise Up scripts to load.
FundraiseUp.openCheckout
, update your installation code to the latest version. Organizations that joined after September 30, 2024, already have the updated code.Parameters
Parameter | Description | Example | Type |
---|---|---|---|
config.modifyAmount | Prevents supporters from changing the donation amount. | true | Boolean |
config.modifyDesignation | Prevents supporters from changing the designation. | true | Boolean |
customFields | Additional fields passed to checkout for tracking purposes as key-value pairs. | referralSource: "Newsletter" | Object |
designations.id | Sets a designation using its ID. | EXXXXXXX | String |
donation.amount | Prefills the donation amount. Fundraise Up doesn't accept donations with cents (or other fractional currency units) by default. Contact us to enable fractional amounts. | 150 | Number |
donation.currency | Sets the donation currency using ISO 4217 codes (USD for US dollars, EUR for euros). | USD | String |
donation.recurring | Sets the donation frequency. Available options: once, daily, weekly, biweekly, every4weeks, monthly, bimonthly, quarterly, semiannual, annual. | monthly | String |
fundraiser | Opens checkout for a specific Fundraiser using either its default Fundraise Up ID (like NXXXXXXX) or a custom ID set by the organization. The custom ID is defined in the Fundraiser URL field when creating the Fundraiser in the Dashboard. | NXXXXXXX 5003-000000D8cu_IQAA | String |
supporter.email | Prefills the supporter's email address. | example@example.com | String |
supporter.firstName | Prefills the supporter's first name. | Alex | String |
supporter.lastName | Prefills the supporter's last name. | Garcia | String |
tribute.honoree | Prefills the tribute honoree field. | Mom and Dad | String |
Configuration interface (TypeScript)
1interface FundraiseUpOpenCheckoutOptions {
2 donation?: {
3 amount?: number;
4 currency?: string;
5 recurring?: string;
6 };
7 supporter?: {
8 firstName?: string;
9 lastName?: string;
10 email?: string;
11 };
12 tribute?: {
13 honoree?: string;
14 };
15 designations?: Array<{
16 id: string;
17 }>;
18 customFields?: {
19 [key: string]: string;
20 };
21 config?: {
22 modifyAmount?: boolean;
23 modifyDesignation?: boolean;
24 };
25 fundraiser?: string;
26}
27
Example usage
This example opens checkout with prefilled supporter information and a $25 monthly donation, while preventing the supporter from changing the amount:
1FundraiseUp.openCheckout('FUNXXXXXXXX', {
2 donation: {
3 amount: 25,
4 currency: 'USD',
5 recurring: 'monthly',
6 },
7 supporter: {
8 firstName: 'Alex',
9 lastName: 'Garcia',
10 email: 'example@example.com',
11 },
12 designations: [{ id: 'EXXXXXXX' }],
13 customFields: {
14 referralSource: 'Newsletter',
15 campaignName: 'Spring Appeal',
16 notes: 'Interested in volunteering',
17 },
18 config: {
19 modifyAmount: false,
20 modifyDesignation: true,
21 },
22});
23
Event Handler Registration method
Method: FundraiseUp.on
This method tracks Fundraise Up conversion events in external applications. You can use it to track events in marketing tools and analytics systems, as well as access real-time data on donations, subscriptions, and supporter activity.
You can:
- Create custom triggers in analytics platforms like Google Tag Manager or Google Analytics.
- Send events to marketing pixels for audience building and advertising on platforms like Google Ads and Microsoft Advertising.
- Trigger automated workflows in your CRM when donations complete.
Here's the basic syntax:
1FundraiseUp.on(eventName: string, callback: Function)
Available events
For the Checkout Modal, we push three events:
checkoutOpen
checkoutClose
donationComplete
For Campaign Pages, we push two events:
checkoutOpen
donationComplete
Event payload structure
All events share the same payload structure. The fields included are the same, but the values may vary depending on the event:
checkoutOpen
provides only metadata and contextual information.checkoutClose
may include supporter and donation details — or may containnull
values if no donation was completed.donationComplete
always includes full supporter and donation data.
Payload examples
checkoutOpen
1{
2 "customFields": {
3 "fiscal_year": "fy2025",
4 "form": "DonateNow"
5 },
6 "livemode": true,
7 "campaign": {
8 "id": "FUNXXXXXXXX",
9 "code": "C-INT-0000",
10 "name": "General Donations"
11 },
12 "utm": {
13 "source": "",
14 "campaign": "",
15 "medium": "",
16 "content": "",
17 "term": ""
18 },
19 "element": {
20 "id": "XXXXXXXX",
21 "type": "Donate Button",
22 "name": "Header Nav - Donate"
23 }
24}
checkoutClose after a successful donation
1{
2 "customFields": {
3 "fiscal_year": "fy2025",
4 "form": "DonateNow"
5 },
6 "livemode": true,
7 "campaign": {
8 "id": "FUNXXXXXXXX",
9 "code": "C-INT-0000",
10 "name": "General Donations"
11 },
12 "utm": {
13 "source": "",
14 "campaign": "",
15 "medium": "",
16 "content": "",
17 "term": ""
18 },
19 "element": {
20 "id": "XXXXXXXX",
21 "type": "Donate Button",
22 "name": "Header Nav - Donate"
23 },
24 "supporter": {
25 "id": "SXXXXXXX",
26 "email": "example@example.com",
27 "firstName": "Alex",
28 "lastName": "Garcia",
29 "anonymous": false,
30 "mailingListSubscribed": false,
31 "employer": null,
32 "onBehalfOf": null
33 },
34 "donation": {
35 "id": "DXXXXXXX",
36 "paymentMethod": "CreditCard",
37 "amount": 56,
38 "feesCovered": 2.24,
39 "currency": "USD",
40 "recurring": false,
41 "frequency": "once"
42 },
43 "designation": {
44 "id": "EXXXXXXX",
45 "name": "the greatest need",
46 "code": "F-INT-0001"
47 },
48 "tribute": null,
49 "recurring": {
50 "id": "RXXXXXXX"
51 },
52 "comment": null
53}
checkoutClose without a successful donation
1{
2 "customFields": {
3 "fiscal_year": "fy2025",
4 "form": "DonateNow"
5 },
6 "livemode": true,
7 "campaign": {
8 "id": "FUNXXXXXXXX",
9 "code": "C-INT-0000",
10 "name": "General Donations"
11 },
12 "utm": {
13 "source": "",
14 "campaign": "",
15 "medium": "",
16 "content": "",
17 "term": ""
18 },
19 "element": {
20 "id": "XXXXXXXX",
21 "type": "Donate Button",
22 "name": "Header Nav - Donate"
23 },
24 "supporter": {
25 "id": null,
26 "email": "example@example.com",
27 "firstName": "Alex",
28 "lastName": "Garcia",
29 "anonymous": false,
30 "mailingListSubscribed": false,
31 "employer": null,
32 "onBehalfOf": null
33 },
34 "donation": null,
35 "designation": null,
36 "tribute": null,
37 "recurring": null,
38 "comment": null
39}
donationComplete
1{
2 "customFields": {
3 "fiscal_year": "fy2025",
4 "form": "DonateNow",
5 "hs_preview": "UvMjiRBY-66781953082"
6 },
7 "livemode": true,
8 "campaign": {
9 "id": "FUNXXXXXXXX",
10 "code": "C-INT-0000",
11 "name": "General Donations"
12 },
13 "utm": {
14 "source": "",
15 "campaign": "",
16 "medium": "",
17 "content": "",
18 "term": ""
19 },
20 "element": {
21 "id": "XXXXXXXX",
22 "type": "Donate Button",
23 "name": "Header Nav - Donate"
24 },
25 "supporter": {
26 "id": "SXXXXXXX",
27 "email": "example@example.com",
28 "firstName": "Alex",
29 "lastName": "Garcia",
30 "anonymous": false,
31 "mailingListSubscribed": false,
32 "employer": null,
33 "onBehalfOf": null
34 },
35 "donation": {
36 "id": "DXXXXXXX",
37 "paymentMethod": "CreditCard",
38 "amount": 5.6,
39 "feesCovered": 0.6,
40 "currency": "USD",
41 "recurring": false,
42 "frequency": "once"
43 },
44 "designation": {
45 "id": "EXXXXXXX",
46 "name": "the greatest need",
47 "code": "F-INT-0001"
48 },
49 "tribute": null,
50 "recurring": {
51 "id": "RXXXXXXX"
52 },
53 "comment": null
54}
Payload fields
This table lists all fields included in the event payload. Some fields may be null
or empty depending on the event and supporter actions.
Parameter | Description | Type |
---|---|---|
customFields.[parameters] | Names and values of any custom fields added to the campaign. | String |
livemode | true if checkout was opened in live mode; false if in test mode. | Boolean |
campaign.id | The Fundraise Up ID of the campaign. | String |
campaign.code | The code assigned to the campaign. Empty if no code is set. | String |
campaign.name | The name of the campaign. | String |
utm.source | The value of the source parameter from the URL that launched checkout. Empty if not present. | String |
utm.campaign | The value of the campaign parameter from the URL that launched checkout. Empty if not present. | String |
utm.medium | The value of the medium parameter from the URL that launched checkout. Empty if not present. | String |
utm.content | The value of the content parameter from the URL that launched checkout. Empty if not present. | String |
utm.term | The value of the term parameter from the URL that launched checkout. Empty if not present. | String |
element.id | The ID of the element used to launch checkout. Empty if not launched from an element. | String |
element.type | The type of the element used to launch checkout (for example, Donate Button). | String |
element.name | The name of the element used to launch checkout. | String |
supporter.id | The Fundraise Up ID of the supporter. null if no donation was submitted. | String |
supporter.email | The email address entered by the supporter. | String |
supporter.firstName | The first name entered by the supporter. | String |
supporter.lastName | The last name entered by the supporter. | String |
supporter.anonymous | true if the Donate anonymously option is enabled and selected; false if enabled but not selected. Omitted if the option is not enabled. | Boolean |
supporter.mailingListSubscribed | true if the mailing list option is enabled and the supporter opted in; false if not. Omitted if the option is not enabled. | Boolean |
supporter.employer | If the employer matching option is enabled and the supporter enters a value, it’s included here. Otherwise, null . | String |
supporter.onBehalfOf | If the “Allow donations on behalf of organizations” option is enabled for the campaign and the supporter enters a value, it’s included here. Otherwise, null . | String |
donation.id | The Fundraise Up ID of the donation. null if no donation was completed. | String |
donation.paymentMethod | The payment method used at checkout. null if no donation was completed. Possible options: creditCard , paypal , applePay , googlePay , clickToPay , ach , acss , ukBacs , auBecsDebit , sepa , venmo , iDEAL . | String |
donation.amount | The total donation amount, including transaction fees. null if no donation was completed. | Number |
donation.feesCovered | The fee amount covered by the supporter. null if no donation was completed. | Number |
donation.currency | The currency selected at checkout. null if no donation was completed. | String |
donation.recurring | true if a recurring frequency was selected; false if one-time. null if no donation was completed. | Boolean |
donation.frequency | The donation frequency selected at checkout. null if no donation was completed. | String |
designation.id | The ID of the selected designation. null if no designation was selected. | String |
designation.name | The name of the selected designation. null if no designation was selected. | String |
designation.code | The code of the selected designation. null if no designation was selected. | String |
tribute | true if the supporter selected the tribute option during checkout; false if not. Included only if the tribute option is enabled. | Boolean |
recurring | The Fundraise Up ID of the recurring plan. null if no plan was created. | Object |
comment | The supporter’s comment, if provided. null if not. | String |
Example usage
Below is an example of how to use the Fundraise Up JavaScript API to send event data to the Feathr Super Pixel tracking code.
1FundraiseUp.on('donationComplete', function(details) {
2 var feathr_amount = details.donation.amount || 0;
3 var feathr_recurring = details.donation.recurring || 'Not Provided';
4 var feathr_currency = details.donation.currency || 'USD';
5 var feathr_fullName = details.supporter.firstName + ' ' + details.supporter.lastName || '';
6 var feathr_email = details.supporter.email || 'Not Provided';
7 var feathr_companies = [details.supporter.employer] || ['Not Provided'];
8
9 feathr("update", {
10 "name": feathr_fullName,
11 "email": feathr_email,
12 "companies": feathr_companies
13 });
14
15 feathr(
16 "convert",
17 "YOUR_CONVERSION_PIXEL_ID",
18 {
19 "amount": feathr_amount,
20 "currency": feathr_currency,
21 "category": "YOUR CONVERSION CATEGORY"
22 },
23 {
24 "RECURRING": feathr_recurring
25 }
26 );
27});
Custom fields
Custom fields added to a Campaign are included in event payloads. For example, the donationComplete
event can send parameters for custom fields like fund
, appeal
, and source
.
1FundraiseUp.on('donationComplete', function(details) {
2 var fund = details.customFields.fund || '';
3 var appeal = details.customFields.appeal || '';
4 var source = details.customFields.source || '';
5});
Testing and debugging
You can debug and test events in your browser’s console. The example below logs the full payload of the checkoutOpen
event:
1FundraiseUp.on('checkoutOpen', function(details) {
2 console.log(details);
3});
Platform guides
Explore how to use the Fundraise Up JavaScript API with popular platforms.
Analytics
Track checkout events and create custom triggers for analytics.
Marketing
Send checkout events to marketing pixels for audience building and advertising.