Charity Reporting API

How Does it Work

At a high level, these are the steps you may want to implement to call the API:

1. Generate a non-expiring Page Access Token with the page_read_donations permission.
2. Use the token to call the endpoints to generate and read transaction reports.
3. Create a job that runs daily to get the latest report available. At this time, reports are usually available with a two day delay from the date of the donation.
4. Paginate through all transactions to get all data for a given report
5. Store the latest date for which you have data and request reports only for new dates.

For more information on transaction reports' availability and data, please refer to the Help Center article.

Generate a Page Access Token

To call the API, you’ll need to use a non-expiring page access token with the page_read_donations permission. Page access tokens are generated via the Facebook Login permission dialog. You can learn about how to generate a page access token from a user access token here: https://developers.facebook.com/docs/pages/getting-started

An admin of the app and charity's Facebook page can use the Graph API Explorer to generate a page access token by selecting the Application from the dropdown list, clicking Get Token, then Get Page Access Token, and following the steps in the dialogs selecting the appropriate charity pages and making sure to select the page_read_donations permission.

Alternatively, you can add a Facebook Login button that requests the page_read_donations permission to your site. The person granting the permission must be an admin of the charity’s Facebook Page for the relevant page to show up in the permission dialog.

The page access token will not expire unless the admin revokes access to your app. More information on page access tokens can be found here: https://developers.facebook.com/docs/pages/access-tokens

Secure your API calls

In the calls below, you’ll notice a field called appsecret_proof. Adding the appsecret_proof parameter adds a level of security by requiring that the call come from your server and requires knowing the app secret. If you're using the official PHP SDK, the appsecret_proof parameter is automatically added.

Although not required to use the API, we also recommend configuring your app to require appsecret_proof in all calls from your app by going to your App Dashboard's Advanced tab and check the Require App Secret option. You can find more information on how to secure your app here: https://developers.facebook.com/docs/graph-api/securing-requests

Generate the Transaction Report

POST /fundraisers/transactions Request

To trigger the generation of a transaction report, make a POST request to /fundraisers/transactions with a page access token. Note that you must call this endpoint as an asyncbatch request or the report may not contain any transactions. Note also that some organizations have a lot of transactions, so it is recommended to generate reports for a single day instead of specifying long date ranges. You can do this by specifying the same value for since and until parameters.

Example Request

curl \
  -F 'access_token={ACCESS_TOKEN}' \
  -F 'appsecret_proof={APPSECRET_PROOF}' \
  -F 'asyncbatch=[
       {
         "method": "POST",
         "relative_url": "fundraisers/transactions",
         "name": "async_session_1",
         "body": "since=1567814400&until=1567900800"
       },
     ]' \
  https://graph.facebook.com

POST /fundraisers/transactions Response

The response contains a list of async_sessions with IDs that can be used in subsequent GET requests to retrieve the report IDs.

Example Response

{
  "async_sessions":[
    {
      "id":"111111111111",
      "name":"async_session_1"
    },
  ]
}

GET {async_session} Request

To use the async session ID from the previous call to get the corresponding report ID, make a GET request to /{async_session_id} with a page access token. This call can also be batched.

Example Request

curl -G -X GET \
  -d fields=result \
  -d access_token={ACCESS_TOKEN} \
  'https://graph.facebook.com/{async_session_id}'

GET {async_session} Response

The response result field contains an id, which is the report_id to be used in a subsequent GET request to retrieve the report.

Example Response

{
  "result":"{
    \"id\":\"{report_id}\"
  }",
  "id":"{async_session_id}"
}

Retrieve the Transaction Report

GET {report_id} Request

To get the transaction report created by an earlier POST request, make a GET request to /{report_id}/transactions with a page access token and appsecret proof.

Example Request

curl -G -X GET \
  -d access_token={ACCESS_TOKEN} \
  -d appsecret_proof={APPSECRET_PROOF} \
  'https://graph.facebook.com/{report_id}/transactions'

GET {report_id} Response

The response will contain a list of transaction objects.

This endpoint supports pagination to get the full list of transactions. Learn more about cursor-based pagination here: https://developers.facebook.com/docs/graph-api/using-graph-api/#paging

The fields below are only available in some countries and if the payment was processed by Meta Payments (US & CA) or Facebook Payments (EU).

Example Response

{
  "data": [
    {
      "payment_id": "123456789123456",
      "charge_time": 1567881064,
      "charge_date": "2019-09-07",
      "charge_action_type": "S",
      "donation_amount": 1224,
      "facebook_fee": 0,
      "net_payout_amount": 1224,
      "payout_currency": "USD",
      "sender_currency": "GBP",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "charity_id": "112233445566778899",
      "fundraiser_id": "998877665544332211",
      "fundraiser_title": "Roger Rabbit's fundraiser to save the world!",
      "fundraiser_owner_name": "Roger Rabbit",
      "permalink_url": "https://www.facebook.com/998877665544332211",
      "source_name": "fundraiser_api",
      "id": "1002003004005"
    },
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUnZA3Y09Ydzg4Tmo3TzdzTnlabF",
      "after": "QVFIUmp6dF9VVlZAERHJHbmRxREhydDW"
    },
    "next": "https://graph.facebook.com/v4.0/*`report_id`*/transactions?after=QVFIUmp6dF9VVlZAERHJHbmRxREhydDW"
  }
}