Fundraisers API

The Fundraisers API is in beta and is available to selected partners. If you are interested in learning more, please fill out the form on this page to be notified of future partnership opportunities: https://nonprofits.fb.com/topic/fundraisers-api/

The Fundraisers API allows a fundraising website to integrate with Facebook to extend the effectiveness, reach and visibility of their campaigns. Campaigns on the fundraising website can be mirrored on Facebook allowing people to raise money on their Facebook Fundraiser, while keeping donation information in sync between the mirrored campaigns.

Graph API endpoints to manage fundraisers on Facebook:

The Fundraisers API requires an access token with the manage_fundraisers permission. Work with your partner engineer to get your app whitelisted for this permission.

Some endpoints allow you to use the app access token in case the user access token is not valid anymore. For security purposes, you should always make these API calls server side and never embed your app access token in a client. This will help prevent malicious developers from impersonating your app.

Create a fundraiser

To create a new fundraiser on behalf a user, make a POST request to /me/fundraisers with a user access token. Making a GET request to this endpoint will list all fundraisers created by your app for the given user.

Request Fields

Field Name Description Type

charity_id [required]

A unique id generated by Facebook; ask your representative for this id.

numeric string

name [required]

Name of the campaign, can be up to 70 characters long.

string

description [required]

Description of your campaign, can be up to 50k characters long.

string

goal_amount [required]

Target goal in currency’s smallest unit. Fundraisers currently support only whole values, so for currencies with cents like USD, you must round to an integer number and then multiply by 100 to get the value in cents. For zero-decimal currencies like JPY, simply provide the integer amount without multiplying by 100.

int

currency [required]

The ISO 4127 code of the currency displayed for the goal amount.

string (ISO 4127)

cover_photo

Cover photo of the fundraiser. Supported file types are JPEG and PNG.

image

end_time [required]

Unix timestamp of when the fundraiser will stop accepting donations. Must be within 5 years from now.

int

external_id [required]

The ID generated by you to identify the fundraiser in your system.

string

fundraiser_type [required]

Must be person_for_charity.

string

external_fundraiser_uri

URI of the fundraiser on the external site.

string

external_event_name

Name of the event this fundraiser belongs to.

string

external_event_uri

URI of the event this fundraiser belongs to.

string

external_event_start_time

Unix timestamp of the day when the event takes place.

string

  • goal_amount must be a positive integers. For currencies with cents like USD, round up the value to an integer and then multiply by 100. For example, $123.45 should be converted to 12400. This is necessary because we only allow users to set goal amounts in whole units. When posting external donations to Facebook, you don't need to round the amount.
  • If you don't pass the cover_photo, the fundraiser will display a default cover photo.
  • To pass the cover_photo you need to upload the image as multipart/form-data.

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "charity_id": 12345,
  "name": "Test Fundraiser",
  "description": "The description for Test Fundraiser",
  "goal_amount": 100000,
  "currency": "USD",
  "end_time": 1501784952,
  "external_id": "ABC123",
  "fundraiser_type": "person_for_charity",
  "external_fundraiser_uri": "https://secure.info-komen.org/site/TR?fr_id=6847&pg=personal&px=123",
  "external_event_name": "2017 Komen DC Race for the Cure",
  "external_event_uri": "https://secure.info-komen.org/site/TR?fr_id=6847&pg=entry",
  "external_event_start_time": 1504970131
}' "https://graph.facebook.com/v2.8/me/fundraisers?access_token=USER_ACCESS_TOKEN"

Response

If the request succeeds, the response object will contain a single field id with the unique identifier of the created object.

Example Response

{
  "id": "1234567"
}

Update a fundraiser

Once you created a fundraiser, you can edit its name, description, goal_amount, or end_time by issuing a POST request to /{fundraiser-id} with a user or app access token.

End a fundraiser

While ending a fundraiser is generally controlled by the user on Facebook, there may be situations where you may need to end all fundraisers to stop receiving donations from Facebook. You can do this by issuing a POST request to /{fundraiser-id}/end_fundraiser with a user or app access token.

Get donations

To list all donations made on Facebook send a GET request to /<fundraiser_id>/donations with a user access token. As any other Graph API endpoint, you can user the fields parameter to specify a comma separated list of fields you want to the response to contain.

You can also get donations data in real-time by creating a Webhook subscription.

Request Fields

Field Name Description Type

limit

Restricts the maximum number of records to get. Must be non-negative.

int

fields

List of fields to be retrieved for each donation record. The list may contain the following values: amount_received, currency, donation_time, donor_id_hash, fundraiser, payment_id.

Comma separated list of strings.

Example Request

curl "https://graph.facebook.com/v2.8/<fundraiser_id>/donations?access_token=USER_ACCESS_TOKEN&limit=1&fields=amount_received,donation_time,donor_id_hash,fundraiser,id,currency,payment_id"

Response Fields

The following fields may be included in the response for each object in the data array:

Field Name Description Type

amount_received

Donation amount received in cents.

int

currency

ISO 4127 code of the amount_received currency.

string (ISO 4127)

donation_time

The time when the donation occurred, in ISO 8601 format.

string (ISO 8601)

donor_id_hash

Hash of the donor ID, unique for the same donor across all fundraisers for a given nonprofit.

string

payment_id

Graph API ID of the payment transaction.

numeric string

fundraiser.id

Graph API ID of the fundraiser object.

numeric string

id

Graph API ID of the donation object.

numeric string

Example Response

{
  "data": [
    {
      "amount_received": 500,
      "donation_time": "2017-03-01T16:03:08+0000",
      "donor_id_hash": "BA1C...bSA",
      "fundraiser": {
        "id": "1234567"
      },
      "id": "987654321",
      "currency": "USD",
      "payment_id": "135792468"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFI...FR",
      "after": "QVFI...FR"
    }
  }
}

For additional information about the available parameters please check Graph API Reading

Create and delete external donations

To update the counter on the Facebook fundraiser page, you need to let Facebook know about donations happening on your site. You can do this by making a POST request to /<fundraiser_id>/external_donations with an app access token.

The amount_received must be in the same currency that you set when creating the fundraiser. Unlike the goal_amount, you should not round this number even though the Fundraiser page does not show cents.

For example, if you pass a donation of $10.20 as 1020, then the progress UI will show $10. If you then pass another donation of $9.80, the total will correctly be added to show $20.

If you need to delete the donation, issue a DELETE request to the Graph API node ID that it was returned to you when creating the donation.

There is no support for updating an existing external donation. If you need to do so, you can delete the external donation and create a new one with the updated information.

Example Requests

curl -X POST -H "Content-Type: application/json" -d '{
  "amount_received": 4000,
  "currency": "USD",
  "donation_id_hash": "3857768956349",
  "donor_id_hash": "4587387354",
  "donation_time": 1488387995
}' "https://graph.facebook.com/v2.8/<fundraiser_id>/external_donations?access_token=APP_ACCESS_TOKEN"
curl -X DELETE "https://graph.facebook.com/v2.8/<external_donation_id>?access_token=APP_ACCESS_TOKEN"

Response

If the POST request succeeds, the response will contain a single field id with the unique identifier of the new Graph API object. This is the id that you can use to delete the external donation.

Example Response

{
  "id": "9876543"
}

Parameters

Property Name Description Type

amount_received [required]

Donation amount received in cents. MUST be non-negative and in the corresponding fundraiser currency, not the currency of the actual donation.

int

currency [required]

This MUST be the currency set in the Fundraisers API, not the currency of the actual donation. ISO 4127 codes only.

string

donation_id_hash [required]

Hash of the donation id on the external fundraiser for de-duplication purposes. This is unique per charity_id across all fundraisers.

string

donor_id_hash [required]

Hash of the donor ID, unique for the same donor across all fundraisers for a given nonprofit.

string

donation_time [required]

Unix timestamp of when the donation occurred on your platform.

int

Get real-time donation data

To keep donation data in sync on your platform, Facebook can send real-time updates to your servers via a webhook. To do this, create a webhook subscription for the fundraiser_donations field. Refer to the Webhook documentation to learn how to setup a webhook subscription for your app.

Facebook will send an HTTPS POST request to your callback URL when someone makes a donation to a fundraiser created by your app. The body of the request will contain a JSON payload as described in the Webhook documentation, including these donation fields:

Field Name Description Type

id

Graph API ID of the donation object.

numeric string

fundraiser_id

Graph API ID of the fundraiser object.

numeric string

amount_received

Donation amount received in cents.

int

currency

ISO 4127 code of the amount_received currency.

string (ISO 4127)

donation_time

Unix timestamp of when the donation occurred.

int

donor_id_hash

Hash of the donor ID, unique for the same donor donating more than once to the same fundraiser.

string

payment_id

Graph API ID of the payment transaction.

numeric string

Example Request

[
  {
    "object": "application",
    "entry": [
      {
        "id": "9186349565458",
        "time": 1478311580,
        "changes": [
          {
            "field": "fundraiser_donations",
            "value": {
              "id": 1323410515135,
              "fundraiser_id": 41312314512132,
              "amount_received": 2000,
              "currency": "USD",
              "donation_time": 1478311562,
              "donor_id_hash": "BARDSADm0341341kuv...",
              "payment_id": 12312312123
            }
          }
        ]
      }
    ]
  }
]

FAQ

Testing

Q: How can I create a test fundraiser?

A: All fundraisers on Facebook are public, but it's possible to create a test fundraiser that is visible only to developers of your app. To do that, you can simply create a fundraiser using an app “In development” mode. Fundraisers created this way will show a banner at the top that explains that the fundraiser is visible to app developers only. When switching your app from “In development” to “Live”, your test fundraisers will continue to stay hidden from the general public. Fundraisers created by a “Live” app will stay public even if the app is set back to “In development”.

Q: What's the difference between an app being “In development” or “Live”?

A: Fundraisers created using a live app will be live and publicly visible whereas fundraisers created using a dev app are only visible to the app's developers and admins. Live and dev mode fundraisers can receive donations, but webhooks are only sent when the app is live.

Q: How can I test donations?

A: At this time we don't support test donations and all donations must be made with a valid payment credential. The minimum amount you can donate is $5 and you can request for a refund using the contact form listed on this page.

Q: How can I test webhooks?

A: Apps in development mode don't receive a webhook event when a donation is made, which makes it challenging to create an end-to-end test. Because of this, you have two options to test the webhook: you can manually trigger a webhook event from your developer dashboard; or you can create a fundraiser using an app that is “In Development” (so that the fundraiser won't be public) and then switch the app to “Live” so that webhooks can be received when you make a donation.

Refunds

Q: How can donors request for a refund?

A: People that donated on Facebook can request a refund using the form here: https://www.facebook.com/help/contact/162031714239823

Q: Is the fundraiser updated when a refund is issued?

A: Currently, when a donation is refunded, the fundraiser on Facebook won't reflect the refund and the total amount raised will stay the same. No webhook event will be fired to notify you of the refund.

Q: How should I handle refunds on the nonprofit site?

A: If someone donates on your site and later requests for a refund, you should keep the donation amount in sync with Facebook. For full refunds, you can simply delete the external donation that you previously posted. For partial refunds, you can delete the external donation and then post a new one with the updated amount.

Participant Actions

Q: What happens if a user deletes their fundraiser via Facebook?

A: While uncommon, people can delete their fundraiser on Facebook. When this happens, any graph API call that references the fundraiser will return an error. Since there is no webhook to let you know that a fundraiser has been deleted in real time, you can handle the deletion when you get an error back when trying to read the fundraiser or post a new external donation. Deleting a fundraiser can't be undone, so you should handle the deletion as permanent. At this point, you may want to offer a way for the person to re-connect to Facebook on your participant center to create a new fundraiser on Facebook.

Q: What happens if a user deletes their fundraiser and then later creates a new one via the API?

A: The new fundraiser on Facebook will start fresh and will not reflect any previous donations. To account for previous donations, you should post as external donations any donation that was received so far, including any donation that was previously received on Facebook. This should ensure that the total amount raised matches what is shown on your site.

Q: How should we handle user's leaving an event or transferring to a new event?

A: You can decide whether you want to end the Facebook fundraiser in these cases. For participant transfers, you can update the end date via the api to ensure the Facebook fundraiser ends according to the new event date.

Facebook Donations

Q: Who can make donations or create fundraisers on Facebook?

A: We support donations from a specific list of countries. A complete list of countries can be found here: https://www.facebook.com/help/837523116348786. People that can't donate, will see the donate button grayed out.

Q: Why do donors see an error message when attempting to donate?

A: There could be an issue with the card the donor is attempting to use. Try removing and re-adding the card from payments settings: https://secure.facebook.com/settings?tab=payments&section=settings.

Q: How can I access a transaction report showing donations received on Facebook?

A: You can download transaction reports for a single day or a specified date range from the organization's page.

Q: Can transaction reports be downloaded programmatically?

A: No, at this time transaction reports are available only from the organization's page settings.

Q: Why doesn't the fundraiser_donations webhook include the donor's name?

A: Donors can customize the privacy of their donations on Facebook. To preserve donor privacy, we don't share this information via the webhook.

Q: Can we get donor information based on Payment ID?

A: Currently, there isn't a method to obtain donor information based on Payment ID. You can download transaction reports with donor names and amounts from the organization's Facebook page.

Fundraiser Features

Q: Where can we learn about new features related to Fundraising on Facebook?

A: You can learn more about the tools available to nonprofits here at https://nonprofits.fb.com, and you can find an overview of the Fundraisers API here at https://nonprofits.fb.com/topic/fundraisers-api.

Q: How does matching work for the Fundraisers API?

A: Currently, matching is not available for fundraisers created via the API.