JavaScript API - Givetly

Explore the functionality of givetly’s JavaScript API designed to enhance your fundraising process.

Notice something off? Want more details? Hard to follow? Give us your feedback

Overview

The JavaScript API is an efficient tool developed for organizations to optimize their fundraising processes and engage more effectively with donors. It consists of two primary methods:

Open Checkout: Triggers the checkout based on various events or conditions, with pre-set information such as donation amounts or supporter details.
Event Handler Registration: Enables tracking of conversion events within external applications and systems not inherently supported.

Each method, along with its parameters, is outlined in the sections that follow.

Details on each method

Open Checkout Method

Method: Givetly.openCheckout

This method provides the capability for the checkout to open based on multiple triggers or events. This allows for dynamic interaction, such as auto-filling donor details or the donation amount when users reach a specific part of your website or finish engaging with a media piece.

Parameters like supporter details, donation amount, and currency can be pre-filled. Below is the example spread of parameters.

Givetly.openCheckout(campaignId: string, options?: GivetlyOpenCheckoutOptions)

Note: Ensure your installation code is updated to the latest version to utilize the openCheckout method. Organizations onboarding post-September 30, 2024, are exempt from this requirement.

Parameters

Parameter	Description	Example	Type
`supporter.firstName`	First name of the supporter.	Dawes	String
`supporter.lastName`	Last name of the supporter.	Case	String
`supporter.email`	Email of the supporter.	[email protected]	String
`donation.amount`	Donation amount.	150	Number
`donation.currency`	Donation currency (ISO 4217 code).	USD	String
`donation.recurring`	Frequency of the donation.	monthly	String
`tribute.honoree`	Name for tribute donation.	Mom and Dad	String
`designations.id`	Donation designation by ID.	EHHJ9R36	String
`customFields`	Additional tracking fields.	`notes`: Volunteering	String
`config.modifyAmount`	Allow modification of donation amount.	true	Boolean
`config.modifyDesignation`	Allow modification of designation.	true	Boolean

Example Usage

Givetly.openCheckout("FUNTFERHMEC", {

  donation: {

    amount: 10,

    currency: "EUR",

    recurring: "monthly",

  },

  supporter: {

    firstName: "Emily",

    lastName: "Smith",

    email: "[email protected]",

  },

  tribute: {

    honoree: "Mom and Dad",

  },

  designations: [{ id: "EHHJ9R36" }],

  customFields: {

    test: "value",

    code: "some-code",

    referralSource: "Social Media",

    campaignName: "Spring Fundraiser",

    notes: "This is a recurring donation.",

    preferredContactMethod: "email",

  },

  config: {

    modifyAmount: true,

    modifyDesignation: true,

  },

});

Event Handling

With the JavaScript API, organizations can track and manage conversion events in analytics tools and marketing platforms by utilizing the Event Handler Registration method.

Event Handler Registration Method

Method: Givetly.on

This method is designed to monitor conversion events across external applications. It can be used to capture events triggered from user interaction with the Checkout modal and Campaign Page.

Givetly.on(eventName: string, callback: Function)

Integrate this method with conversion events for tracking and structuring custom triggers through systems like Google Analytics or Tag Manager. Push events to marketing platforms for optimized ad strategies.

Explore further: JavaScript API playground

Events

For the Checkout modal, we track:

checkoutOpen
checkoutClose
donationComplete

For the Campaign Page, we push:

checkoutOpen
donationComplete

These events and their payloads are detailed further in their respective sections.

checkoutOpen

This event triggers whenever a Checkout modal or Campaign Page is opened.

{

  "customFields": {

    "fiscal_year": "fy2023",

    "form": "DonateNow"

  },

  "livemode": true,

  "campaign": {

    "id": "FUNCPJTZZQR",

    "code": "C-INT-0000",

    "name": "General Donations"

  },

  "utm": {

    "source": "",

    "campaign": "",

    "medium": "",

    "content": "",

    "term": ""

  },

  "element": {

    "id": "XTGWFZFR",

    "type": "Donate Button",

    "name": "Header Nav - Donate"

  }

}

Parameters

Parameter	Type	Description
`customfields.[parameters]`	String	Names and values for any custom fields added to the campaign.
`livemode`	Boolean	Indicates if test mode was not used for the donation.
`campaign.id`	String	Unique campaign ID.
`campaign.code`	String	The code assigned to the campaign.
`campaign.name`	String	The campaign name.
`utm.source`	String	Source parameter if included in the URL that launched Checkout.
`utm.campaign`	String	Campaign parameter if included in the URL that launched Checkout.
`utm.medium`	String	Medium parameter if included in the URL that launched Checkout.
`utm.content`	String	Content parameter if included in the URL that launched Checkout.
`utm.term`	String	Term parameter if included in the URL that launched Checkout.
`element.id`	String	Unique ID of the Elements component used to launch Checkout.
`element.type`	String	Type of Elements component (e.g., Donate Button).
`element.name`	String	Name of the Elements component used to launch Checkout.

checkoutClose

This event triggers every time the Checkout modal is closed, regardless of whether a donation was completed. Supporter information such as name and email is captured even if the checkout is closed before completing a donation.

After a Successful Donation

{

  "customFields": {

    "fiscal_year": "fy2023",

    "form": "DonateNow"

  },

  "livemode": true,

  "campaign": {

    "id": "FUNCPJTZZQR",

    "code": "C-INT-0000",

    "name": "General Donations"

  },

  "utm": {

    "source": "",

    "campaign": "",

    "medium": "",

    "content": "",

    "term": ""

  },

  "element": {

    "id": "XTGWFZFR",

    "type": "Donate Button",

    "name": "Header Nav - Donate"

  },

  "supporter": {

    "id": "SBLQMBBU",

    "email": "[email protected]",

    "firstName": "Caractacus",

    "lastName": "Potts",

    "anonymous": false,

    "mailingListSubscribed": false,

    "employer": null,

    "onBehalfOf": null

  },

  "donation": {

    "id": "DNNLGBJF",

    "paymentMethod": "CreditCard",

    "amount": 25,

    "feesCovered": 1.5,

    "currency": "USD",

    "recurring": false,

    "frequency": "once"

  },

  "designation": {

    "id": "EXVNFMNX",

    "name": "food for the hungry",

    "code": "F-INT-0014"

  },

  "tribute": null,

  "recurring": {

    "id": "RNXGXWWR"

  },

  "comment": null

}

Without a Successful Donation

{

  "customFields": {

    "fiscal_year": "fy2023",

    "form": "DonateNow"

  },

  "livemode": true,

  "campaign": {

    "id": "FUNCPJTZZQR",

    "code": "C-INT-0000",

    "name": "General Donations"

  },

  "utm": {

    "source": "",

    "campaign": "",

    "medium": "",

    "content": "",

    "term": ""

  },

  "element": {

    "id": "XTGWFZFR",

    "type": "Donate Button",

    "name": "Header Nav - Donate"

  },

  "supporter": {

    "id": null,

    "email": "[email protected]",

    "firstName": "Caractacus",

    "lastName": "Potts",

    "anonymous": false,

    "mailingListSubscribed": false,

    "employer": null,

    "onBehalfOf": null

  },

  "donation": null,

  "designation": null,

  "tribute": null,

  "recurring": null,

  "comment": null

}

Parameters

Parameter	Type	Description
`customfields.[parameters]`	String	Names and values for any custom fields added to the campaign.
`livemode`	Boolean	Indicates if test mode was not used for the donation.
`campaign.id`	String	Unique campaign ID.
`campaign.code`	String	The code assigned to the campaign.
`campaign.name`	String	The campaign name.
`utm.source`	String	Source parameter if included in the URL that launched Checkout.
`utm.campaign`	String	Campaign parameter if included in the URL that launched Checkout.
`utm.medium`	String	Medium parameter if included in the URL that launched Checkout.
`utm.content`	String	Content parameter if included in the URL that launched Checkout.
`utm.term`	String	Term parameter if included in the URL that launched Checkout.
`element.id`	String	Unique ID of the Elements component used to launch Checkout.
`element.type`	String	Type of Elements component (e.g., Donate Button).
`element.name`	String	Name of the Elements component used to launch Checkout.
`supporter.id`	String	Unique supporter ID.
`supporter.email`	String	Supporter’s email address.
`supporter.firstName`	String	Supporter’s first name.
`supporter.lastName`	String	Supporter’s last name.
`supporter.anonymous`	Boolean	Indicates if the “Donate anonymously” option was selected.
`supporter.mailingListSubscribed`	Boolean	If mailing list is enabled, this shows if the option was selected.
`supporter.employer`	String	If company matching is enabled and a value is entered, it gets stored, otherwise it is null.
`supporter.onBehalfOf`	String	If donating on behalf of an organization is enabled and a value is entered, it gets stored, otherwise it is null.
`donation.id`	String	Unique donation ID.
`donation.paymentMethod`	String	Payment method used at checkout (e.g., CreditCard, PayPal).
`donation.amount`	Number	Total donation amount including transaction fees.
`donation.feesCovered`	Number	Fee amount assessed for the donation.
`donation.currency`	String	Currency selected at checkout.
`donation.recurring`	Boolean	Indicates if a recurring donation was made.
`donation.frequency`	String	Donation frequency selected at checkout.
`designation.id`	String	Unique designation ID.
`designation.name`	String	Name of the designation selected at checkout.
`designation.code`	String	Code of the designation selected at checkout.
`tribute.type`	Boolean	If tribute feature is enabled, reflects if the option was selected.
`comment`	String	Any comment entered during the checkout process.

donationComplete

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

{

  "customFields": {

    "fiscal_year": "fy2023",

    "form": "DonateNow",

    "hs_preview": "UvMjiRBY-66781953082"

  },

  "livemode": true,

  "campaign": {

    "id": "FUNCPJTZZQR",

    "code": "C-INT-0000",

    "name": "General Donations"

  },

  "utm": {

    "source": "",

    "campaign": "",

    "medium": "",

    "content": "",

    "term": ""

  },

  "element": {

    "id": "XTGWFZFR",

    "type": "Donate Button",

    "name": "Header Nav - Donate"

  },

  "supporter": {

    "id": "STMNACDG",

    "email": "[email protected]",

    "firstName": "Tulsi",

    "lastName": "Lattimer",

    "anonymous": false,

    "mailingListSubscribed": false,

    "employer": null,

    "onBehalfOf": null

  },

  "donation": {

    "id": "DPPSCTFU",

    "paymentMethod": "CreditCard",

    "amount": 5.6,

    "feesCovered": 0.6,

    "currency": "USD",

    "recurring": false,

    "frequency": "once"

  },

  "designation": {

    "id": "EHHJ9R36",

    "name": "the greatest need",

    "code": "F-INT-0001"

  },

  "tribute": null,

  "recurring": {

    "id": "RNXGXWWR"

  },

  "comment": null

}

Parameters

Parameter	Type	Description
`customFields.[parameters]`	String	An array containing names and values for any custom fields added to the campaign
`livemode`	Boolean	`true` indicates the donation was not made in test mode.
`campaign.id`	String	The campaign’s unique ID
`campaign.code`	String	Code assigned to the campaign
`campaign.name`	String	Name of the campaign
`utm.source`	String	Source parameter value included in the URL, if any
`utm.campaign`	String	Campaign parameter value included in the URL, if any
`utm.medium`	String	Medium parameter value included in the URL, if any
`utm.content`	String	Content parameter value included in the URL, if any
`utm.term`	String	Term parameter value included in the URL, if any
`element.id`	String	ID of the Elements component that triggered Checkout
`element.type`	String	Type of Elements component used (like Donate Button)
`element.name`	String	Name of the Elements component used
`supporter.id`	String	Alphanumeric supporter ID
`supporter.email`	String	Email address of the supporter
`supporter.firstName`	String	First name of the supporter
`supporter.lastName`	String	Last name of the supporter
`supporter.anonymous`	Boolean	`true` if the “Donate anonymously” option was selected
`supporter.mailingListSubscribed`	Boolean	`true` if subscribed to mailing list when enabled at Checkout
`supporter.employer`	String	Stores entered employer information if company matching is enabled at Checkout, otherwise `null`
`supporter.onBehalfOf`	String	Stores information if donating on behalf of an organization, otherwise `null`
`donation.id`	String	Unique alphanumeric donation ID
`donation.paymentMethod`	String	Payment method used (e.g., CreditCard, PayPal)
`donation.amount`	Number	Total donation amount with transaction fees
`donation.feesCovered`	Number	Fees covered by the donation
`donation.currency`	String	Currency selected for the donation
`donation.recurring`	Boolean	`true` if recurring, `false` for one-time donation
`donation.frequency`	String	Donation frequency (e.g., once, Monthly, Annual)
`designation.id`	String	Designation ID, if provided
`designation.name`	String	Name of the designation, if provided
`designation.code`	String	Designation code, if provided
`tribute.type`	Boolean	No assigned value if tribute feature is selected, `null` otherwise
`comment`	String	Comment provided in the Checkout modal or Campaign page, `null` if not provided

Custom Fields

Custom fields within a Campaign appear in event payloads, as seen in the donationComplete event that can handle custom field values such as fund, appeal, and source.

Givetly.on("donationComplete", function (details) {

  var fund = details.customFields.fund || "";

  var appeal = details.customFields.appeal || "";

  var source = details.customFields.source || "";

});

Debugging and Testing

To test or debug events, use your browser’s console to log parameters of the checkoutOpen event:

Givetly.on("checkoutOpen", function (details) {

  console.log(details);

});

Platform Guides

Learn to integrate the JavaScript API with various platforms.

Analytics

Monitor Checkout events and develop custom triggers for analytics purposes.

Marketing

Utilize Checkout event data in marketing pixels for audience targeting and ad campaigns.

Found a mistake? Missing something? Hard to grasp? Share your insights with us.

Integrations

​Overview

​Open Checkout Method

​Parameters

​Example Usage

​Event Handling

​Event Handler Registration Method

​Events

​checkoutOpen

​checkoutClose

​After a Successful Donation

​Without a Successful Donation

​donationComplete

​Custom Fields

​Debugging and Testing

​Platform Guides

​Analytics

​Marketing

Overview

Open Checkout Method

Parameters

Example Usage

Event Handling

Event Handler Registration Method

Events

checkoutOpen

checkoutClose

After a Successful Donation

Without a Successful Donation

donationComplete

Custom Fields

Debugging and Testing

Platform Guides

Analytics

Marketing