CRM and platform integrations

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
`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
`customFields`	Additional custom fields that can be passed to the checkout for tracking purposes.	`referralSource`: Newsletter, `notes`: Interested in volunteering	String
`designations.id`	Sets a designation for the donation using the designation’s ID.	EXXXXXXX	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
`fundraiser`	Opens checkout form for a specific Fundraiser using either its default Fundraise Up ID (like NXXXXXXX) or a custom ID set by the organization. In the API, this custom ID is passed using the `slug` field. In the Dashboard, it’s set as the Fundraiser URL.	NXXXXXXX 5003-000000D8cu_IQAA	String
`supporter.email`	Supporter's email address.	example@example.com	String
`supporter.firstName`	Supporter's first name.	Alex	String
`supporter.lastName`	Supporter's last name.	Garcia	String
`tribute.honoree`	Sets the value for the tribute honoree.	Mom and Dad	String

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  fundraiser?: string;
26}

Example usage

Link copied

1FundraiseUp.openCheckout('FUNXXXXXXXX', {
2  donation: {
3    amount: 10,
4    currency: 'EUR',
5    recurring: 'monthly',
6  },
7  supporter: {
8    firstName: 'Alex',
9    lastName: 'Garcia',
10    email: 'example@example.org',
11  },
12  tribute: {
13    honoree: 'Mom and Dad',
14  },
15  designations: [{ id: 'EXXXXXXX' }],
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  fundraiser: 'NXXXXXXX',
29});

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": "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}

Parameters

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

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": "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": 25,
38    "feesCovered": 1.5,
39    "currency": "USD",
40    "recurring": false,
41    "frequency": "once"
42  },
43  "designation": {
44    "id": "EXXXXXXX",
45    "name": "food for the hungry",
46    "code": "F-INT-0014"
47  },
48  "tribute": null,
49  "recurring": {
50    "id": "RXXXXXXX"
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": "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}

An example of checkoutClose without a successful donation.

Parameters

Parameter	Description	Type
`customfields.[parameters]`	An array containing the names and values for any custom fields added to the campaign	String
`livemode`	Set to `true` if test mode was not used for the donation.	Boolean
`campaign.id`	The alphanumeric Fundraise Up campaign ID	String
`campaign.code`	The code assigned to the campaign. No value if parameter value is not provided	String
`campaign.name`	The name of the campaign	String
`utm.source`	The source parameter value if a source property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.campaign`	The source parameter value if a `campaign` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.medium`	The source parameter value if a `medium` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.content`	The source parameter value if a `content` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.term`	The source parameter value if a `term` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`element.id`	The ID of the Elements component used to launch Checkout. No value if parameter value is not provided	String
`element.type`	The type of Elements component (e.g. Donate Button) used to launch Checkout.	String
`element.name`	The name of the Elements component used to launch Checkout.	String
`supporter.id`	The alphanumeric Fundraise Up supporter ID of the the supporter	String
`supporter.email`	The supporter’s email address	String
`supporter.firstName`	The supporter’s first name	String
`supporter.lastName`	The supporter’s last name	String
`supporter.anonymous`	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	Boolean
`supporter.mailingListSubscribed`	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	Boolean
`supporter.employer`	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`	String
`supporter.onBehalfOf`	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`	String
`donation.id`	The alphanumeric Fundraise Up donation ID	String
`donation.paymentMethod`	The payment method used at checkout. Options: `creditCard`, `paypal`, `applePay`, `googlePay`, `clickToPay`, `ach`, `acss`, `ukBacs`, `auBecsDebit`, `sepa`, `venmo`, `iDEAL`	String
`donation.amount`	The total donation amount, including transaction fees	Number
`donation.feesCovered`	The fee amount assessed for the donation	Number
`donation.currency`	The currency selected at checkout	String
`donation.recurring`	`true` if a recurring frequency was selected at checkout, `false` if a one-time donation was made	Boolean
`donation.frequency`	The donation frequency selected at checkout. Options: `once`, `Daily`, `Weekly`, `Biweekly`, `Every 4 weeks`, `Monthly`, `Bimonthly`, `Quarterly`, `Semiannual`, `Annual`	String
`designation.id`	The alphanumeric Fundraise Up identifier of the designation selected at checkout. No value if parameter value is not provided	String
`designation.name`	The name of the designation selected at checkout. No value if parameter value is not provided	String
`designation.code`	The alphanumeric code of the designation selected at checkout. No value if parameter value is not provided	String
`tribute.type`	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`	Boolean
`comment`	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`.	String

donationComplete

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

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}

Parameters

Parameter	Description	Type
`customfields.[parameters]`	An array containing the names and values for any custom fields added to the campaign	String
`livemode`	Set to `true` if test mode was not used for the donation.	Boolean
`campaign.id`	The campaign ID	String
`campaign.code`	The code assigned to the campaign. No value if parameter value is not provided	String
`campaign.name`	The name of the campaign	String
`utm.source`	The source parameter value if a source property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.campaign`	The source parameter value if a `campaign` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.medium`	The source parameter value if a `medium` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.content`	The source parameter value if a `content` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`utm.term`	The source parameter value if a `term` property is included in the URL that launched Checkout. No value if parameter value is not provided	String
`element.id`	The ID of the Elements component used to launch Checkout. No value if parameter value is not provided	String
`element.type`	The type of Elements component (e.g. Donate Button) used to launch Checkout.	String
`element.name`	The name of the Elements component used to launch Checkout.	String
`supporter.id`	The alphanumeric Fundraise Up supporter ID of the the supporter	String
`supporter.email`	The supporter’s email address	String
`supporter.firstName`	The supporter’s first name	String
`supporter.lastName`	The supporter’s last name	String
`supporter.anonymous`	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	Boolean
`supporter.mailingListSubscribed`	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	Boolean
`supporter.employer`	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`	String
`supporter.onBehalfOf`	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`	String
`donation.id`	The alphanumeric Fundraise Up donation ID	String
`donation.paymentMethod`	The payment method used at checkout. Options: `creditCard`, `paypal`, `applePay`, `googlePay`, `clickToPay`, `ach`, `acss`, `ukBacs`, `auBecsDebit`, `sepa`, `venmo`, `iDEAL`	String
`donation.amount`	The total donation amount, including transaction fees	Number
`donation.feesCovered`	The fee amount assessed for the donation	Number
`donation.currency`	The currency selected at checkout	String
`donation.recurring`	`true` if a recurring frequency was selected at checkout, `false` if a one-time donation was made	Boolean
`donation.frequency`	The donation frequency selected at checkout. Options: `once`, `Daily`, `Weekly`, `Biweekly`, `Every 4 weeks`, `Monthly`, `Bimonthly`, `Quarterly`, `Semiannual`, `Annual`	String
`designation.id`	The alphanumeric Fundraise Up identifier of the designation selected at checkout. No value if parameter value is not provided	String
`designation.name`	The name of the designation selected at checkout. No value if parameter value is not provided	String
`designation.code`	The alphanumeric code of the designation selected at checkout. No value if parameter value is not provided	String
`tribute.type`	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`	Boolean
`comment`	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`.	String

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