Did you know that Give comes packaged with a powerful API that allows you to expose donation data in either JSON or XML format? This is very useful for other developers to query data about your donation forms, donations, donors and more.

Generating API Keys

In order to access the API you will first need to generate the proper access keys for your user account.

To do that, simply go to your user profile, and at the very bottom of the screen you’ll see a section called “Give API Keys”.

Generate Give API Keys
Generate Give API Keys

Check the box that says “Generate API Keys” and then click “Update Profile”. The page will refresh and then you’ll see your Give API keys there instead.

Give API Keys
Give API Keys

Accessing the API

Now that you have generated an API key, let’s look into how we can use these keys to interact with the API. To access the API enter in the following URL:

http://yoursite.com/give-api/stats/?key=<Public API key here>&token=<token here>

*Be sure to swap out the key and token with actual keys.

The secret key is used for internal authentication and should never be used to directly access the API.
Please note: If you have not accessed the API before and receive a 404 error then you may have to refresh your WordPress permalinks by going to Settings > Permalinks in the WordPress admin.

API Endpoints

The API has four endpoints, each for performing a specific kind of request:

  • stats – For retrieving earnings / sales stats specific dates, date ranges, and specific forms.
  • forms – For retrieving info about donation forms such as title, donation levels, and goal.
  • donors – For retrieving donor statistics such as name, address.
  • donations – For retrieving recent donations and info about each donation (donor, donation amount, etc).
  • subscriptions – For retrieving recurring subscriptions and info about each subscription (donor, intitial date, recurrence, etc).

Note: The subscriptions endpoint is only present if the site is using our Recurring Donations add-on.

The endpoints are used like so:

http://yoursite.com/give-api/<endpoint>/

For example:

http://yoursite.com/give-api/donations/

When combined with the API key and user, the complete URL looks like this:

http://yoursite.com/give-api/donations/?key=a281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

Response Format

Give provides API responses in two formats:

To specify the format returned (jSON will be used if none is specified), simply add the format argument to the URL:

http://yoursite.com/give-api/donations/?key=a281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&format=xml

Paging Parameters

By default, the Give API will return 10 results per page for the donors, donations, and form queries.

If a query has 20 results, the first ten will be displayed by default, but then the second 10 can be accessed by adding &page=2 to the query string, like so:

http://yoursite.com/give-api/donations/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&page=2

You can change the number of results returned by using the number parameter. This example will return 25 results per page:

http://yoursite.com/give-api/donations/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&number=25
If you want to retrieve all results (no paging), set number parameter to -1.

Stats Query

The stats query is used for retrieving donation statistics from your Give integration. It can be used to retrieve total donations for the current month, last year, or for a specific date range. It can also be used for retrieving stats for a specific or just one donation form.

The stats endpoint is:

http://yoursite.com/give-api/v1/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=<QUERY TYPE>

Note that the stats query requires a type parameter to be passed. There are two type options:

  • donations – For retrieving donation stats.
  • earnings – For retrieving earning stats.

Both sales and earnings query types include additional parameters for date and form options:

  • date – The date to retrieve earnings or donations for. This has three accepted values:
    • today – Will retrieve stats for the current day.
    • yesterday – Will retrieve stats for the previous day.
    • range – Will retrieve stats for a date range.
      • startdate – Format: YYYYMMDD. Example: 20120224 = 2012/02/24
      • enddate – Format: YYYYMMDD. Example: 20120531 = 2012/02/24
  • form – used to retrieve sale or earnings stats for a specific donation form or all forms. This option has two accepted values:
    • # – The form ID to retrieve stats for.
    • all – Retrieve stats for all forms. Note: this option does not support paging.
Note: the donations and date options cannot be combined. You may only use one or the other.

A basic earnings stats query looks like this:

http://yoursite.com/give-api/v1/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=earnings

And the response is:

{
    "earnings": {
        "today": 0,
        "current_month": 300,
        "last_month": 0,
        "totals": 300
    },
    "request_speed": 0.01496696472168
}

A basic donation stats query looks like this:

http://yoursite.com/give-api/v1/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=donations

And the response is:

{
    "donations": {
        "today": 0,
        "current_month": "13",
        "last_month": 0,
        "totals": 13
    },
    "request_speed": 0.0044069290161133
}

Forms Query

The forms endpoint allows you to retrieve information about your donation forms. A basic forms query looks like this:

http://yoursite.com/give-api/v1/forms/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

A sample forms response looks like this:

{
    "forms": [
        {
            "info": {
                "id": 28,
                "slug": "custom-amount-text",
                "title": "Custom Amount Text",
                "create_date": "2015-07-13 16:14:08",
                "modified_date": "2015-07-16 16:54:27",
                "status": "publish",
                "link": "http://local.wordpress.dev/?post_type=give_forms&p=28",
                "content": "Dixere proximus locum tegi. Convexi ulla lucis caesa tuti manebat. Orba radiis nisi pulsant. Animalia sui mutatas obstabatque. Colebat declivia praeter sata ventis zephyro septemque. Congestaque sine glomeravit dissociata. Consistere fulminibus deducite. Erant quisque inposuit subdita certis. Iunctarum dedit diverso reparabat indigestaque fuerant!",
                "thumbnail": false
            },
            "goal": {
                "amount": "55.000000",
                "percentage_completed": 0
            },
            "stats": {
                "total": {
                    "donations": "0",
                    "earnings": "0"
                },
                "monthly_average": {
                    "donations": "0",
                    "earnings": "0"
                }
            },
            "pricing": {
                "amount": "30.00"
            }
        },
        {
            "info": {
                "id": 15,
                "slug": "multi-level-sample-form-1",
                "title": "Multi-level Sample Form 1",
                "create_date": "2015-07-11 12:47:03",
                "modified_date": "2015-07-11 12:47:03",
                "status": "publish",
                "link": "http://local.wordpress.dev/?post_type=give_forms&p=15",
                "content": "",
                "thumbnail": false
            },
            "stats": {
                "total": {
                    "donations": "6",
                    "earnings": "100"
                },
                "monthly_average": {
                    "donations": "6",
                    "earnings": "100"
                }
            },
            "pricing": {
                "basiclevel": "10.00",
                "intermediatelevel": "20.00",
                "advancedlevel": "50"
            }
        },
        {
            "info": {
                "id": 7,
                "slug": "save-the-forests",
                "title": "Save the Forests",
                "create_date": "2015-07-11 12:15:04",
                "modified_date": "2015-07-11 12:15:04",
                "status": "publish",
                "link": "http://local.wordpress.dev/?post_type=give_forms&p=7",
                "content": "",
                "thumbnail": false
            },
            "stats": {
                "total": {
                    "donations": "1",
                    "earnings": "30"
                },
                "monthly_average": {
                    "donations": "1",
                    "earnings": "30"
                }
            },
            "pricing": {
                "amount": "30.00"
            }
        }
    ],
    "request_speed": 0.011187076568604
}

If you want to retrieve info for only a specific form, you can pass a form ID via the form parameter:

http://yoursite.com/give-api/v1/forms/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc661790d70&form=55

The goal data is only present for forms with goals enabled.

Donors Query

The donors endpoint allows you to query the database and retrieve a list of donors who have donated using the forms on your website. A basic donors query looks like this:

http://yoursite.com/give-api/v1/donors/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&number=25

For each customer returned, the following information is returned for each customer:

  • id – The WordPress user ID. If they donated as a guest, this will return empty.
  • username – The WordPress user login name. If the donated as a guest, this will return blank.
  • display_name – The WordPress user display name. If the donated as a guest, this will return blank.
  • donor_id – The Give Donor ID assigned to this donor.
  • first_name – If the donated as a guest, this will return the Give’s donor first name. If an account was created at the time of donation then the WP user first name will display.
  • last_name -If the donated as a guest, this will return the Give’s donor last name. If an account was created at the time of donation then the WP user last name will display.
  • email – The donor’s email address.
  • total_donations – The total number of donations the person has made.
  • total_spent – The total amount the donor has donated.

A donors query response looks like this:

{
    "donors": [
        {
            "info": {
                "id": "",
                "user_id": "",
                "username": "",
                "display_name": "",
                "customer_id": "3",
                "first_name": "Jane",
                "last_name": "Smith",
                "email": "jsmith@gmail.com"
            },
            "stats": {
                "total_purchases": "4",
                "total_spent": "120.000000"
            }
        },
        {
            "info": {
                "id": "",
                "user_id": "",
                "username": "",
                "display_name": "",
                "customer_id": "2",
                "first_name": "John",
                "last_name": "Doe",
                "email": "jdoe@gmail.com"
            },
            "stats": {
                "total_purchases": "5",
                "total_spent": "90.000000"
            }
        },
        {
            "info": {
                "id": "1",
                "user_id": "1",
                "username": "admin",
                "display_name": "admin",
                "customer_id": "1",
                "first_name": "Devin",
                "last_name": "Walker",
                "email": "devin@wordimpress.com"
            },
            "stats": {
                "total_purchases": "4",
                "total_spent": "90.000000"
            }
        }
    ],
    "request_speed": 0.0060648918151855
}

If you wish to retrieve the info for a specific customer, you can add the &donor={identifier} parameter, like this:

http://yoursite.com/give-api/donors/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&donor=1

or

http://yoursite.com/give-api/donors/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&donor=email@domain.com

The response for a single customer will be like this:

{
    "donors": [
        {
            "info": {
                "user_id": "1",
                "username": "admin",
                "display_name": "admin",
                "customer_id": "1",
                "first_name": "Devin",
                "last_name": "Walker",
                "email": "devin@wordimpress.com"
            },
            "stats": {
                "total_donations": "4",
                "total_spent": "90.000000"
            }
        }
    ],
    "request_speed": 0.00553297996521
}

The Give Rest API allows you to trigger events based on donation activity in unique ways. For example, our Zapier Add-on uses the Give Rest API to send data to Zapier and trigger events in any of their supported services.

Donations Query

The donations endpoint allows for you to query the database and retrieve information for recent donations. A basic donations query looks like this:

http://yoursite.com/give-api/v1/donations/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

For each donation returned, the following information will be available:

  • ID – The donation ID number.
  • key -The donation key.
  • total – The total donation amount.
  • gateway – The payment method, such as stripe or paypal, used to make the donation.
  • email – The email address associated with the sale.
  • date – The date the donation was made.
  • form – The form used to make the donation:
    • id – The form ID.
    • name – The name of the form.
    • price – The price of the donation form.
    • price_name – The level option name that was donation (if the form has multi-level donation prices).

An example sales query response looks like this:

{
    "donations": [
        {
            "ID": 54,
            "transaction_id": 54,
            "key": "ae98c52dd8710c460ecb31a1ba9b538b",
            "total": 20,
            "gateway": "manual",
            "email": "devin@wordimpress.com",
            "date": "2015-07-14 18:03:07",
            "form": {
                "id": 15,
                "name": "Multi-level Sample Form 1",
                "price": "20.00",
                "price_name": "Intermediate Level"
            }
        },
        {
            "ID": 31,
            "transaction_id": 31,
            "key": "bc75711721d345ea4a335bca60e544da",
            "total": 30,
            "gateway": "manual",
            "email": "jdoe@gmail.com",
            "date": "2015-07-13 19:16:42",
            "form": {
                "id": 7,
                "name": "Save the Forests",
                "price": "30.00"
            }
        }
    ],
    "request_speed": 0.023215055465698
}

Notice how the first entry is a multi-level form and the second is a standard form.

Supscriptions Query

The supbscriptions endpoint allows for you to query the database and retrieve information for recent subscriptions. A basic subscriptions query looks like this:

http://yoursite.com/give-api/v1/subscriptions/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

For each subscription returned, the data is separated into two sub-objects, info and payments. The info object contains the data pertaining to the subscription itself, and the payments object contains the info pertaining to the renewal donations on each subscription.

Subscriptions info object

  • subs_db – An array of the database table holding the subscription.
  • id -The subscription ID.
  • donor_id -The donor ID associated with the subscription.
  • period – The subscription frequency (day/week/month/year).
  • initial_amount – The parent donation amount.
  • recurring_amount – The amount that recurs each month.
  • bill_times – How many recurrences before the subscription is completed. 0 indicates unlimited/until cancelled.
  • transaction_id – The Payment Gateway transaction ID for the parent payment
  • parent_payment_id – The (Give) ID of the parent payment.
  • form_id – The form ID.
  • created – The date the subscription was created.
  • expiration – The renewal date (when it will charge again or cancel depending on settings.)
  • status – The subscription status.
  • profile_id – The Subscription ID from the gateway, if applicable.
  • gateway – The Payment Gateway used.
  • donor – An array of data about the donor
  • notes – Notes added (manually or automatically generated) about the subscription.

Subscriptions Payment Object

Inside the Payments object, 4 data points for each renewal donation are returned:

  • id – The donation ID
  • amount – The amount of the donation
  • date – The date of the renewal
  • status – The status of the renewal

An example subscriptions query response looks like this:

{
    "subscriptions": [
        {
            "info": {
                "subs_db": {
                    "table_name": "wp_give_subscriptions",
                    "primary_key": "id",
                    "version": "1.1",
                    "min_index_length": 191
                },
                "id": "31",
                "donor_id": "71",
                "period": "week",
                "frequency": "1",
                "initial_amount": "13.000000",
                "recurring_amount": "13.000000",
                "bill_times": "0",
                "transaction_id": "40019834114",
                "parent_payment_id": "1328",
                "form_id": "1325",
                "created": "2018-10-09 09:52:29",
                "expiration": "2018-11-06 23:59:59",
                "status": "active",
                "profile_id": "5371285",
                "gateway": "authorize",
                "donor": {
                    "id": "71",
                    "purchase_count": "5",
                    "purchase_value": "63.000000",
                    "email": "jink@recurrably.example",
                    "emails": {
                        "primary": "jink@recurrably.example"
                    },
                    "name": "Jimbo Franklin",
                    "date_created": "2018-10-09 15:48:24",
                    "payment_ids": "1328,1336,1360,1375",
                    "user_id": "15",
                    "notes": [],
                    "address": [],
                    "token": "",
                    "verify_key": "",
                    "verify_throttle": "0000-00-00 00:00:00"
                },
                "notes": ""
            },
            "payments": [
                {
                    "id": 1375,
                    "amount": "13.000000",
                    "date": "October 30, 2018",
                    "status": "renewal"
                },
                {
                    "id": 1360,
                    "amount": "13.000000",
                    "date": "October 23, 2018",
                    "status": "renewal"
                },
                {
                    "id": 1336,
                    "amount": "13.000000",
                    "date": "October 16, 2018",
                    "status": "renewal"
                }
            ]
        },
}

Version Parameter

The Give API has a built-in versioning parameter to help keep it backwards compatible when new updates are created.

There are two methods of specifying an API version. The first is adding /v{number}/ to your API URL like this:

https://site.com/give-api/v1/{endpoints}

The second is adding a constant to your wp-config.php file like this:

define( 'GIVE_API_VERSION', 'v1' );

If neither of these methods is used the latest version of the API is always delivered simply by going to /give-api/donations (or any other slug used by Give) with the proper token and API key.

API Request Logging

By default, Give will log all API request attempts. The main purpose of the API request logs is to provide a means of monitoring how the API is being used. The log entries for API requests can be seen at Give > Reports > Logs > API Requests:

The Logs Screen showing the API log
The Logs Screen showing the API log

 

If you wish to disable API Request logging, simply add this filter:

add_filter( 'give_api_log_requests', '__return_false' );