GiveWP API Reference
Did you know that GiveWP 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 within the WordPress Dashboard, and you’ll see a section called “Account Management” where the option to generate GiveWP API Keys are located.
Check the box that says “Generate API Keys” and then click “Update Profile”. The page will refresh and then you’ll see your GiveWP API keys there instead.
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.
Note: The secret key is used for internal authentication and should never be used to directly access the API.
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
GiveWP 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 GiveWP 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
Note: 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 GiveWP 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 form 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 GiveWP Donor ID assigned to this donor.
- first_name – If the donated as a guest, this will return the GiveWP’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 GiveWP’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 GiveWP Rest API allows you to trigger events based on donation activity in unique ways. For example, our Zapier Add-on uses the GiveWP 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. 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 – 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.
Query a single donation
In case you want to query a single donation, you can do that by passing the ID (donation ID) as a parameter to the URL, like the following:
http://yoursite.com/give-api/donations/?key=f60dbeb484de8e7153e2f2fee458115c&token=9ec2682da90af362df172ffd76bd3721&id=188
A single donation query response looks like this:
{
"donations":[
{
"ID":188,
"number":"72",
"transaction_id":"ch_1IlEEzFaskRwvTTgWjfElIAW",
"key":"389fcff68fe8174d82ss18902a2a2017",
"total":"50.00",
"status":"Renewal",
"gateway":"stripe",
"name":"John Doe",
"fname":"John",
"lname":"Joe",
"email":"johndoe@example.org",
"date":"2021-04-28 13:19:19",
"payment_meta":{
"_give_payment_donor_id":"1",
"_give_donor_billing_address1":"",
"_give_donor_billing_address2":"",
"_give_donor_billing_city":"",
"_give_donor_billing_state":"",
"_give_donor_billing_zip":"",
"_give_donor_billing_country":"",
"_give_donor_billing_first_name":"John",
"_give_donor_billing_last_name":"Doe",
"_give_payment_donor_email":"johndoe@example.org",
"_give_payment_currency":"USD",
"_give_payment_transaction_id":"ch_1IlEEzFaskRwvTTgWjfElIAW",
"_give_payment_gateway":"stripe",
"_give_payment_donor_ip":"168.187.216.72",
"subscription_id":"1"
},
"form":{
"id":"8",
"name":"Donation Form",
"price":"50.00",
"price_name":"$50.00",
"price_id":"2"
}
}
],
"request_speed":0.014397144317626953
}
Subscriptions Query
The subscriptions 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 (GiveWP) 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 GiveWP 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 GiveWP) with the proper token and API key.
API Request Logging
By default, GiveWP 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 GiveWP > Reports > Logs > API Requests:
If you wish to disable API Request logging, simply add this filter:
add_filter( 'give_api_log_requests', '__return_false' );
