JavaScript API

Explore Fundraise Up’s JavaScript API.

The Fundraise Up JavaScript API is designed to help organizations improve their fundraising workflow and better engage with donors. This tool offers two methods:

Open Checkout: This method enables the Fundraise Up checkout to open based on different events or triggers, with pre-filled parameters such as the donation amount or supporter information.
Event Handler Registration: This method enables you to track Fundraise Up conversion events in external applications and systems that are not 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

Link copied

Method: FundraiseUp.openCheckout

This method makes the Fundraise Up checkout open in response to various events or triggers. Organizations can dynamically populate the checkout with custom data based on user interactions on their website, such as scrolling to a specific point or finishing a video.

By passing the necessary parameters when opening the checkout, you can create tailored scenarios and integrate them into complex interfaces.

You can pre-fill fields such as supporter details, donation amount, currency, and more. For a complete list of parameters, refer to the table below.

1FundraiseUp.openCheckout(campaignId: string, options?: FundraiseUpOpenCheckoutOptions)

This method works immediately and doesn't require waiting for our scripts to fully load.

To use the FundraiseUp.openCheckout method, you need to update the Fundraise Up installation code to the latest version. This update is not required for organizations that joined after September 30, 2024.

Parameters

Link copied

Parameter	Description	Example	Type
`supporter.firstName`	Supporter's first name.	Dawes	String
`supporter.lastName`	Supporter's last name.	Case	String
`supporter.email`	Supporter's email address.	dawes.case@gmail.com	String
`donation.amount`	Donation Amount. By default, Fundraise Up doesn't automatically accept donations with cents (or other fractional currency units). However, you can enable this feature by contacting your personal Customer Success Manager or our Support Team. Learn more →	150	Number
`donation.currency`	Currency of the donation. You must specify the currency by its ISO 4217 alphabetic code (for example, `currency=USD` for the US dollar).	USD	String
`donation.recurring`	Sets the donation frequency.	once daily weekly biweekly every4weeks monthly bimonthly quarterly semiannual annual	String
`tribute.honoree`	Sets the value for the tribute honoree.	Mom and Dad	String
`designations.id`	Sets a designation for the donation using the designation’s ID.	EHHJ9R36	String
`customFields`	Additional custom fields that can be passed to the checkout for tracking purposes.	`referralSource`: Newsletter, `notes`: Interested in volunteering	String
`config.modifyAmount`	Disallow the supporter to modify the donation amount set by the `amount` parameter.	true	Boolean
`config.modifyDesignation`	Disallow the supporter to modify the designation set by the URL parameter, `designationId`.	true	Boolean

Configuration object interface (TypeScript)

Link copied

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}

Example usage

Link copied

1FundraiseUp.openCheckout('FUNTFERHMEC', {
2  donation: {
3    amount: 10,
4    currency: 'EUR',
5    recurring: 'monthly',
6  },
7  supporter: {
8    firstName: 'Emily',
9    lastName: 'Smith',
10    email: 'emily.smith@example.org',
11  },
12  tribute: {
13    honoree: 'Mom and Dad',
14  },
15  designations: [{ id: 'EHHJ9R36' }],
16  customFields: {
17    test: 'value',
18    code: 'some-code',
19    referralSource: 'Social Media',
20    campaignName: 'Spring Fundraiser',
21    notes: 'This is a recurring donation.',
22    preferredContactMethod: 'email',
23  },
24  config: {
25    modifyAmount: true,
26    modifyDesignation: true,
27  }
28});

Event handling

Link copied

You can use the JavaScript API to track Fundraise Up conversion events in marketing tools and analytics systems, as well as access real-time data on donations, subscriptions, and supporter activity. To do this, use the Event Handler Registration method.

Event Handler Registration method

Link copied

Method: FundraiseUp.on

This method is primarily used to track Fundraise Up conversion events in external applications. The JavaScript API pushes events based on user interactions with the Checkout modal and the Campaign Page.

1FundraiseUp.on(eventName: string, callback: Function)

For example, you can use donation events to create custom triggers and track properties in analytics platforms like Google Tag Manager or Google Analytics. These events can also be sent to marketing pixels for audience building and advertising on platforms like Google Ads and Microsoft Advertising.

Try it: JavaScript API playground

Implementation example

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});

Events

Link copied

For the Checkout modal, we push three events:

checkoutOpen
checkoutClose
donationComplete

For the Campaign Page, we push two events:

checkoutOpen
donationComplete

The behavior of these events, along with example payloads for each, is described below.

checkoutOpen

This event is triggered every time a Checkout modal or a Campaign Page is opened.

1{
2  "customFields": {
3    "fiscal_year": "fy2023",
4    "form": "DonateNow"
5  },
6  "livemode": true,
7  "campaign": {
8    "id": "FUNCPJTZZQR",
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": "XTGWFZFR",
21    "type": "Donate Button",
22    "name": "Header Nav - Donate"
23  }
24}

Parameters

Parameter	Type	Description
`customfields.[parameters]`	String	An array containing the names and values for any custom fields added to the campaign
`livemode`	Boolean	Set to `true` if test mode was not used for the donation.
`campaign.id`	String	The alphanumeric Fundraise Up campaign ID
`campaign.code`	String	The code assigned to the campaign. No value if parameter value is not provided
`campaign.name`	String	The name of the campaign
`utm.source`	String	The source parameter value if a source property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.campaign`	String	The source parameter value if a `campaign` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.medium`	String	The source parameter value if a `medium` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.content`	String	The source parameter value if a `content` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.term`	String	The source parameter value if a `term` property is included in the URL that launched Checkout. No value if parameter value is not provided
`element.id`	String	The alphanumeric Fundraise Up ID of the Elements component used to launch Checkout. No value if parameter value is not provided
`element.type`	String	The type of Elements component (e.g. Donate Button) used to launch Checkout.
`element.name`	String	The name of the Elements component used to launch Checkout.

checkoutClose

This event is triggered every time the Checkout modal is closed, regardless of whether a donation was completed. If the Checkout is closed before completing a donation, details like the supporter’s name and email will still be captured and sent.

After a successful donation

1{
2  "customFields": {
3    "fiscal_year": "fy2023",
4    "form": "DonateNow"
5  },
6  "livemode": true,
7  "campaign": {
8    "id": "FUNCPJTZZQR",
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": "XTGWFZFR",
21    "type": "Donate Button",
22    "name": "Header Nav - Donate"
23  },
24  "supporter": {
25    "id": "SBLQMBBU",
26    "email": "example@mail.com",
27    "firstName": "Caractacus",
28    "lastName": "Potts",
29    "anonymous": false,
30    "mailingListSubscribed": false,
31    "employer": null,
32    "onBehalfOf": null
33  },
34  "donation": {
35    "id": "DNNLGBJF",
36    "paymentMethod": "CreditCard",
37    "amount": 25,
38    "feesCovered": 1.5,
39    "currency": "USD",
40    "recurring": false,
41    "frequency": "once"
42  },
43  "designation": {
44    "id": "EXVNFMNX",
45    "name": "food for the hungry",
46    "code": "F-INT-0014"
47  },
48  "tribute": null,
49  "recurring": {
50    "id": "RNXGXWWR"
51  },
52  "comment": null
53}

An example of the CheckoutClose event after a successful donation. This event has the same parameters as donationComplete.

Without a successful donation

1{
2  "customFields": {
3    "fiscal_year": "fy2023",
4    "form": "DonateNow"
5  },
6  "livemode": true,
7  "campaign": {
8    "id": "FUNCPJTZZQR",
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": "XTGWFZFR",
21    "type": "Donate Button",
22    "name": "Header Nav - Donate"
23  },
24  "supporter": {
25    "id": null,
26    "email": "example@mail.com",
27    "firstName": "Caractacus",
28    "lastName": "Potts",
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}

An example of checkoutClose without a successful donation.

Parameters

Parameter	Type	Description
`customfields.[parameters]`	String	An array containing the names and values for any custom fields added to the campaign
`livemode`	Boolean	Set to `true` if test mode was not used for the donation.
`campaign.id`	String	The alphanumeric Fundraise Up campaign ID
`campaign.code`	String	The code assigned to the campaign. No value if parameter value is not provided
`campaign.name`	String	The name of the campaign
`utm.source`	String	The source parameter value if a source property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.campaign`	String	The source parameter value if a `campaign` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.medium`	String	The source parameter value if a `medium` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.content`	String	The source parameter value if a `content` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.term`	String	The source parameter value if a `term` property is included in the URL that launched Checkout. No value if parameter value is not provided
`element.id`	String	The ID of the Elements component used to launch Checkout. No value if parameter value is not provided
`element.type`	String	The type of Elements component (e.g. Donate Button) used to launch Checkout.
`element.name`	String	The name of the Elements component used to launch Checkout.
`supporter.id`	String	The alphanumeric Fundraise Up supporter ID of the the supporter
`supporter.email`	String	The supporter’s email address
`supporter.firstName`	String	The supporter’s first name
`supporter.lastName`	String	The supporter’s last name
`supporter.anonymous`	Boolean	If the Donate anonymously option is enabled for Checkout, the value will be `true` if the option is selected, and `false` if the option is not selected
`supporter.mailingListSubscribed`	Boolean	If the mailing list feature is enabled for Checkout, the value is `true` if the option is selected, and `false` when the option is not selected
`supporter.employer`	String	If the company matching feature is enabled for Checkout and a supporter inputs a value, the value is stored for the `supporter.employer` parameter, otherwise, the value is `null`
`supporter.onBehalfOf`	String	If the option to donate on behalf of an organization is enabled for Checkout and a supporter inputs a value, the value is stored for the `supporter.onBehalfOf` parameter, otherwise, the value is `null`
`donation.id`	String	The alphanumeric Fundraise Up donation ID
`donation.paymentMethod`	String	The payment method used at checkout. Options: `creditCard`, `paypal`, `applePay`, `googlePay`, `clickToPay`, `ach`, `acss`, `ukBacs`, `auBecsDebit`, `sepa`, `venmo`, `iDEAL`
`donation.amount`	Number	The total donation amount, including transaction fees
`donation.feesCovered`	Number	The fee amount assessed for the donation
`donation.currency`	String	The currency selected at checkout
`donation.recurring`	Boolean	`true` if a recurring frequency was selected at checkout, `false` if a one-time donation was made
`donation.frequency`	String	The donation frequency selected at checkout. Options: `once`, `Daily`, `Weekly`, `Biweekly`, `Every 4 weeks`, `Monthly`, `Bimonthly`, `Quarterly`, `Semiannual`, `Annual`
`designation.id`	String	The alphanumeric Fundraise Up identifier of the designation selected at checkout. No value if parameter value is not provided
`designation.name`	String	The name of the designation selected at checkout. No value if parameter value is not provided
`designation.code`	String	The alphanumeric code of the designation selected at checkout. No value if parameter value is not provided
`tribute.type`	Boolean	If the tribute feature is enabled and a supporter selected the option during checkout, no value is assigned. If the option was not selected, the value is `null`
`comment`	String	A comment entered into the Comment input in the Checkout modal or Campaign page. If no text was entered into the Comment input, the value will be `null`.

donationComplete

This event is triggered when a donation is successfully completed in Checkout.

1{
2  "customFields": {
3    "fiscal_year": "fy2023",
4    "form": "DonateNow",
5    "hs_preview": "UvMjiRBY-66781953082"
6  },
7  "livemode": true,
8  "campaign": {
9    "id": "FUNCPJTZZQR",
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": "XTGWFZFR",
22    "type": "Donate Button",
23    "name": "Header Nav - Donate"
24  },
25  "supporter": {
26    "id": "STMNACDG",
27    "email": "tulsi.lattimer@gmail.com",
28    "firstName": "Tulsi",
29    "lastName": "Lattimer",
30    "anonymous": false,
31    "mailingListSubscribed": false,
32    "employer": null,
33    "onBehalfOf": null
34  },
35  "donation": {
36    "id": "DPPSCTFU",
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": "EHHJ9R36",
46    "name": "the greatest need",
47    "code": "F-INT-0001"
48 },
49  "tribute": null,
50  "recurring": {
51    "id": "RNXGXWWR"
52  },
53  "comment": null
54}

Parameters

Parameter	Type	Description
`customfields.[parameters]`	String	An array containing the names and values for any custom fields added to the campaign
`livemode`	Boolean	Set to `true` if test mode was not used for the donation.
`campaign.id`	String	The campaign ID
`campaign.code`	String	The code assigned to the campaign. No value if parameter value is not provided
`campaign.name`	String	The name of the campaign
`utm.source`	String	The source parameter value if a source property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.campaign`	String	The source parameter value if a `campaign` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.medium`	String	The source parameter value if a `medium` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.content`	String	The source parameter value if a `content` property is included in the URL that launched Checkout. No value if parameter value is not provided
`utm.term`	String	The source parameter value if a `term` property is included in the URL that launched Checkout. No value if parameter value is not provided
`element.id`	String	The ID of the Elements component used to launch Checkout. No value if parameter value is not provided
`element.type`	String	The type of Elements component (e.g. Donate Button) used to launch Checkout.
`element.name`	String	The name of the Elements component used to launch Checkout.
`supporter.id`	String	The alphanumeric Fundraise Up supporter ID of the the supporter
`supporter.email`	String	The supporter’s email address
`supporter.firstName`	String	The supporter’s first name
`supporter.lastName`	String	The supporter’s last name
`supporter.anonymous`	Boolean	If the Donate anonymously option is enabled for Checkout, the value will be `true` if the option is selected, and `false` if the option is not selected
`supporter.mailingListSubscribed`	Boolean	If the mailing list feature is enabled for Checkout, the value is `true` if the option is selected, and `false` when the option is not selected
`supporter.employer`	String	If the company matching feature is enabled for Checkout and a supporter inputs a value, the value is stored for the `supporter.employer` parameter, otherwise, the value is `null`
`supporter.onBehalfOf`	String	If the option to donate on behalf of an organization is enabled for Checkout and a supporter inputs a value, the value is stored for the `supporter.onBehalfOf` parameter, otherwise, the value is `null`
`donation.id`	String	The alphanumeric Fundraise Up donation ID
`donation.paymentMethod`	String	The payment method used at checkout. Options: `creditCard`, `paypal`, `applePay`, `googlePay`, `clickToPay`, `ach`, `acss`, `ukBacs`, `auBecsDebit`, `sepa`, `venmo`, `iDEAL`
`donation.amount`	Number	The total donation amount, including transaction fees
`donation.feesCovered`	Number	The fee amount assessed for the donation
`donation.currency`	String	The currency selected at checkout
`donation.recurring`	Boolean	`true` if a recurring frequency was selected at checkout, `false` if a one-time donation was made
`donation.frequency`	String	The donation frequency selected at checkout. Options: `once`, `Daily`, `Weekly`, `Biweekly`, `Every 4 weeks`, `Monthly`, `Bimonthly`, `Quarterly`, `Semiannual`, `Annual`
`designation.id`	String	The alphanumeric Fundraise Up identifier of the designation selected at checkout. No value if parameter value is not provided
`designation.name`	String	The name of the designation selected at checkout. No value if parameter value is not provided
`designation.code`	String	The alphanumeric code of the designation selected at checkout. No value if parameter value is not provided
`tribute.type`	Boolean	If the tribute feature is enabled and a supporter selected the option during checkout, no value is assigned. If the option was not selected, the value is `null`
`comment`	String	A comment entered into the Comment input in the Checkout modal or Campaign page. If no text was entered into the Comment input, the value will be `null`.

Custom fields

Link copied

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});

Debugging and testing

Link copied

You can debug and test events in your browser’s console. The example below logs the parameters of the checkoutOpen event when triggered.

1FundraiseUp.on('checkoutOpen', function(details) {	
2  console.log(details);
3});

Platform guides

Link copied

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.

In this article