CRM and platform integrations

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

Link copied

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.

To use FundraiseUp.openCheckout, update your installation code to the latest version. Organizations that joined after September 30, 2024, already have the updated code.

Parameters

Link copied

Parameter	Description	Example	Type
`config.modifyAmount`	Controls whether supporters can change the prefilled donation amount. Use `true` to let them edit it, or `false` to lock the amount. Ignored if the prefilled amount is invalid — for example, if it’s 0, missing, outside allowed limits, or uses unsupported fractional values.	true	Boolean
`config.modifyDesignation`	Controls whether supporters can change the prefilled designation. Use `true` to let them edit it, or `false` to lock the designation. If no designation is set, this parameter is ignored and the field becomes editable.	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)

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}
27

Example usage

Link copied

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

Link copied

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

Link copied

For the Checkout Modal, we push three events:

checkoutOpen
checkoutClose
donationComplete

For Campaign Pages, we push two events:

checkoutOpen
donationComplete

Event payload structure

Link copied

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 contain null values if no donation was completed.
donationComplete always includes full supporter and donation data.

Payload examples

Link copied

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}

Multiple designations

Link copied

When multiple designations are enabled for a campaign, the donation payload reflects them through the donation.donationItems[] array. This array is always present and contains one or more donationItem objects, each representing the part of the donation allocated to a designation.

id – unique donation ID for this designation.
amount – amount allocated to this designation.
frequency – donation frequency for this designation.
feesCovered – covered fee amount for this designation.
designation – object containing designation details (id, name, code; code may be empty if not set).
recurring – object containing subscription details (id if a recurring plan exists, otherwise null).

The top-level donation.id, designation.id, and recurring.id may contain only the first donation’s ID or be empty. To retrieve all IDs, use the donation.donationItems[] array.

Example

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": 50,
39    "feesCovered": 2.0,
40    "currency": "USD",
41    "recurring": false,
42    "frequency": "once",
43    "donationItems": [
44      {
45        "id": "DXXXX001",
46        "amount": 30,
47        "frequency": "once",
48        "feesCovered": 1.2,
49        "designation": {
50          "id": "EXXXX001",
51          "name": "Scholarship Fund",
52          "code": "F-SCH-0001"
53        },
54        "recurring": null
55      },
56      {
57        "id": "DXXXX002",
58        "amount": 20,
59        "frequency": "once",
60        "feesCovered": 0.8,
61        "designation": {
62          "id": "EXXXX002",
63          "name": "Emergency Relief",
64          "code": null
65        },
66        "recurring": null
67      }
68    ]
69  },
70  "tribute": null,
71  "recurring": null,
72  "comment": null
73}

Payload fields

Link copied

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 / null
`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 / null
`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 / null
`utm.campaign`	The value of the campaign parameter from the URL that launched checkout. Empty if not present.	String / null
`utm.medium`	The value of the medium parameter from the URL that launched checkout. Empty if not present.	String / null
`utm.content`	The value of the content parameter from the URL that launched checkout. Empty if not present.	String / null
`utm.term`	The value of the term parameter from the URL that launched checkout. Empty if not present.	String / null
`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 / null
`element.name`	The name of the element used to launch checkout.	String / null
`supporter.id`	The Fundraise Up ID of the supporter. `null` if no donation was submitted.	String / null
`supporter.email`	The email address entered by the supporter.	String / null
`supporter.firstName`	The first name entered by the supporter.	String / null
`supporter.lastName`	The last name entered by the supporter.	String / null
`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 / null
`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 / null
`donation.id`	The Fundraise Up ID of the donation. `null` if no donation was completed. For payments with multiple designations, this field may contain only the first donation’s ID or be empty. Use `donation.donationItems[]` for all donation IDs.	String / null
`donation.donationItems[]`	List of individual donations created when a single payment is split across multiple designations.	Array
`donation.donationItems[].id`	ID of the donation created for this designation within the payment.	String
`donation.donationItems[].amount`	Amount allocated to this designation within the payment.	Number
`donation.donationItems[].frequency`	Donation frequency for this designation within the payment.	String
`donation.donationItems[].feesCovered`	Fee covered for this designation within the payment.	Number
`donation.donationItems[].designation.id`	ID of the designation within the payment.	String
`donation.donationItems[].designation.name`	Name of the designation within the payment.	String
`donation.donationItems[].designation.code`	Code of the designation within the payment. `null` if not set.	String / null
`donation.donationItems[].recurring`	The Fundraise Up ID of the recurring plan. `null` if no plan was created.	String / null
`donation.paymentMethod`	The payment method used at checkout. `null` if no donation was completed. Possible options: `CreditCard`, `ApplePay`, `GooglePay`, `PayPal`, `Venmo`, `ACH`, `BECS`, `Bacs`, `PAD`, `SEPA`, `iDEAL`, `Crypto`	String / null
`donation.amount`	The total donation amount, including transaction fees. `null` if no donation was completed.	Number / null
`donation.feesCovered`	The fee amount covered by the supporter. `null` if no donation was completed.	Number / null
`donation.currency`	The currency selected at checkout. `null` if no donation was completed.	String / null
`donation.recurring`	`true` if a recurring frequency was selected; `false` if one-time. `null` if no donation was completed.	Boolean / null
`donation.frequency`	The donation frequency selected at checkout. `null` if no donation was completed.	String / null
`designation.id`	The ID of the selected designation. `null` if no designation was selected.	String / null
`designation.name`	The name of the selected designation. `null` if no designation was selected.	String / null
`designation.code`	The code of the selected designation. `null` if no designation was selected.	String / null
`tribute`	`true` if the supporter selected the tribute option during checkout; `false` if not. Included only if the tribute option is enabled.	Boolean / null
`recurring`	The Fundraise Up ID of the recurring plan. `null` if no plan was created.	Object / null
`comment`	The supporter’s comment, if provided. `null` if not.	String / null

Example usage

Link copied

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

Try it: JavaScript API playground

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

Testing and debugging

Link copied

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

To force the JavaScript API into test mode, add this script to your page:

1<script>
2window.fundraiseup_livemode = false;
3</script>

This prevents real donations from being processed while testing.

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