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
ParameterDescriptionExampleType
config.modifyAmountPrevents supporters from changing the donation amount.trueBoolean
config.modifyDesignationPrevents supporters from changing the designation.trueBoolean
customFieldsAdditional fields passed to checkout for tracking purposes as key-value pairs.referralSource: "Newsletter"Object
designations.idSets a designation using its ID.EXXXXXXXString
donation.amountPrefills the donation amount. Fundraise Up doesn't accept donations with cents (or other fractional currency units) by default. Contact us to enable fractional amounts.150Number
donation.currencySets the donation currency using ISO 4217 codes (USD for US dollars, EUR for euros).USDString
donation.recurringSets the donation frequency. Available options: once, daily, weekly, biweekly, every4weeks, monthly, bimonthly, quarterly, semiannual, annual.monthlyString
fundraiserOpens 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_IQAAString
supporter.emailPrefills the supporter's email address.example@example.comString
supporter.firstNamePrefills the supporter's first name.AlexString
supporter.lastNamePrefills the supporter's last name.GarciaString
tribute.honoreePrefills the tribute honoree field.Mom and DadString

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}

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.

ParameterDescriptionType
customFields.[parameters]Names and values of any custom fields added to the campaign.String
livemodetrue if checkout was opened in live mode; false if in test mode.Boolean
campaign.idThe Fundraise Up ID of the campaign.String
campaign.codeThe code assigned to the campaign. Empty if no code is set.String
campaign.nameThe name of the campaign.String
utm.sourceThe value of the source parameter from the URL that launched checkout. Empty if not present.String
utm.campaignThe value of the campaign parameter from the URL that launched checkout. Empty if not present.String
utm.mediumThe value of the medium parameter from the URL that launched checkout. Empty if not present.String
utm.contentThe value of the content parameter from the URL that launched checkout. Empty if not present.String
utm.termThe value of the term parameter from the URL that launched checkout. Empty if not present.String
element.idThe ID of the element used to launch checkout. Empty if not launched from an element.String
element.typeThe type of the element used to launch checkout (for example, Donate Button).String
element.nameThe name of the element used to launch checkout.String
supporter.idThe Fundraise Up ID of the supporter. null if no donation was submitted.String
supporter.emailThe email address entered by the supporter.String
supporter.firstNameThe first name entered by the supporter.String
supporter.lastNameThe last name entered by the supporter.String
supporter.anonymoustrue if the Donate anonymously option is enabled and selected; false if enabled but not selected. Omitted if the option is not enabled.Boolean
supporter.mailingListSubscribedtrue if the mailing list option is enabled and the supporter opted in; false if not. Omitted if the option is not enabled.Boolean
supporter.employerIf the employer matching option is enabled and the supporter enters a value, it’s included here. Otherwise, null.String
supporter.onBehalfOfIf 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.idThe Fundraise Up ID of the donation. null if no donation was completed.String
donation.paymentMethodThe 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.amountThe total donation amount, including transaction fees. null if no donation was completed. Number
donation.feesCoveredThe fee amount covered by the supporter. null if no donation was completed.Number
donation.currencyThe currency selected at checkout. null if no donation was completed.String
donation.recurringtrue if a recurring frequency was selected; false if one-time. null if no donation was completed.Boolean
donation.frequencyThe donation frequency selected at checkout. null if no donation was completed.String
designation.idThe ID of the selected designation. null if no designation was selected.String
designation.nameThe name of the selected designation. null if no designation was selected.String
designation.codeThe code of the selected designation. null if no designation was selected.String
tributetrue if the supporter selected the tribute option during checkout; false if not. Included only if the tribute option is enabled.Boolean
recurringThe Fundraise Up ID of the recurring plan. null if no plan was created.Object
commentThe supporter’s comment, if provided. null if not.String

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

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

Platform guides

 
Link copied

Explore how to use the Fundraise Up JavaScript API with popular platforms.

Marketing

Send checkout events to marketing pixels for audience building and advertising.

 

In this article