Introduction

Welcome to the Patreon Platform! Get familiar with the Patreon platform products and tools using the tutorials and references below.

Please note: almost all of this documentation is geared towards software developers. If any of it is confusing, please contact us at [email protected]

While the Platform and this documentation are primarily geared towards developers for now, we do plan to have some more plug-n-play solutions in the coming months. Please contact [email protected] with any tips about how we can help you.

Feedback

If you find any errors in this document, please submit an issue or a pull request on the open source github repo for this document

API Libraries

We've written some open source libraries to help you use our platform services.

Javascript

import url from 'url'
import patreonAPI, { oauth as patreonOAuth } from 'patreon'

const CLIENT_ID = 'pppp'
const CLIENT_SECRET = 'pppp'
const patreonOAuthClient = patreonOAuth(CLIENT_ID, CLIENT_SECRET)

const redirectURL = 'http://mypatreonapp.com/oauth/redirect'

Available on npm

Install

npm install --save patreon

View the source on github

PHP

Available on packagist

Install

composer require patreon/patreon

View the source on github

Java

Get the artifact from Maven

    <dependency>
        <groupId>com.patreon</groupId>
        <artifactId>patreon</artifactId>
        <version>0.0.3</version>
    </dependency>

View the source on github

Ruby

Get the gem from RubyGems

Install

gem install patreon

View the source on github

Python

Get the egg from PyPI, typically via pip:

Install

pip install patreon

or

echo "patreon" >> requirements.txt
pip install -r requirements.txt

Make sure that, however you install patreon, you install its dependencies as well

View the source on github

Third Party Libraries

There are a number of third party libraries that the developer community has created. If you would like to add yours to this list, please email [email protected]

Go

View the source on github

.NET

View the source on github

Clients and API Keys

In order to interact with the Patreon API, you have to register your application with the Patreon platform

Register your application here

OAuth

import url from 'url'
import patreonAPI, { oauth as patreonOAuth } from 'patreon'

const CLIENT_ID = 'pppp'
const CLIENT_SECRET = 'pppp'
const patreonOAuthClient = patreonOAuth(CLIENT_ID, CLIENT_SECRET)

const redirectURL = 'http://mypatreonapp.com/oauth/redirect'

function handleOAuthRedirectRequest(request, response) {
    const oauthGrantCode = url.parse(request.url, true).query.code

    patreonOAuthClient.getTokens(oauthGrantCode, redirectURL, (tokensError, { access_token }) => {
        const patreonAPIClient = patreonAPI(access_token)

        patreonAPIClient(`/current_user`, (currentUserError, apiResponse) => {
            if (currentUserError) {
                console.error(currentUserError)
                response.end(currentUserError)
            }

            response.end(apiResponse);
        })
    })
})

Patreon is building an OAuth provider service — the technology that lets you log in to Medium with Twitter, log in to Disqus with Google+, and even log in to Patreon with Facebook. Below, you’ll find a technical process document that explains how to begin integrating with us. This document assumes technical competency in HTTP protocols and URL structure, and administrative access & developer control of the server that you wish to integrate with Patreon.

Step 1 - Registering Your Client

To set up, you must first register your client application with us. Please visit the Clients & API Keys page to register one.

Step 2 - Making the Log In Button

Request [2]

GET www.patreon.com/oauth2/authorize
    ?response_type=code
    &client_id=<your client id>
    &redirect_uri=<one of your redirect_uris that you provided in step 0>
    &scope=<optional list of requested scopes>
    &state=<optional string>

Once your client is registered, you should create a “Log in with Patreon” and/or “Link your Patreon account” button on your site which directs users to the following URL:

HTTP Request

GET www.patreon.com/oauth2/authorize

Query Parameters

Parameter	Description
response_type Required	Defaults to code
client_id Required	Your client id
redirect_uri Required	one of your redirect_uris that you provided in step 1
scope	This optional parameter will default to users pledges-to-me my-campaign, which fetches user profile information, pledges to your creator, and your creator info.
state	This optional parameter will be transparently appended as a query parameter when redirecting to your redirect_uri. This should be used as CSRF, and can be used as session/user identification as well. E.g. https://www.patreon.com/oauth2/authorize?response_type=code&client_id=123&redirect_uri=https://www.mysite.com/custom-uri&state=their_session_id. On this page, users will be asked if they wish to grant your client access to their account info. When they grant or deny access, they will be redirected to the provided redirect_uri (so long as it is pre-registered with us).

Step 3 - Handling OAuth Redirect

Request [3]

GET https://www.mysite.com/custom-uri
    ?code=<single use code>
    &state=<string>

When the link in Step 2 redirects to the provided redirect_uri, e.g. https://www.mysite.com/custom-uri, it will bring extra HTTP query parameters as follows (assuming the user granted your client access):

Step 4 - Validating Receipt of the OAuth Token

Request [4]

POST api.patreon.com/oauth2/token
    ?code=<single use code, as passed in to GET route [2]>
    &grant_type=authorization_code
    &client_id=<your client id>
    &client_secret=<your client secret>
    &redirect_uri=<redirect_uri>

Your server should handle GET requests in Step 3 by performing the following request on the server, not as a redirect

which will return a JSON response of:

{
    "access_token": <single use token>,
    "refresh_token": <single use token>,
    "expires_in": <token lifetime duration>,
    "scope": <token scopes>,
    "token_type": "Bearer"
}

to be stored on your server, one pair per user.

Step 5 - Using the OAuth Token

You may use the received access_token to make API calls. For example, a typical first usage of the new access_token would be to fetch the user's profile info, and either merge that into their existing account on your site, or make a new account for them. You could then use their pledge level to show or hide certain parts of your site.

Step 6 - Resolving the OAuth Redirect

To reiterate, requests [4] and [5] should be performed by your server (synchronously or asynchronously) in response to receiving the GET request in request [3].

Once your calls are complete, you will have the user’s profile info and pledge level for your creator.

If requests [4] and [5] were performed synchronously, then you can return a HTTP 302 for their GET in request [3], redirecting to a page with appropriate success dialogs & profile information. If the requests in requests [4] and [5] are being performed asynchronously, your response to request [3] should probably contain AJAX code that will notify the user once requests [4] and [5] are completed.

Step 7 - Keeping up to date

<?php
require_once('vendor/patreon/patreon/src/patreon.php');
use Patreon\API;
use Patreon\OAuth;
// Get your current "Creator's Access Token" from https://www.patreon.com/platform/documentation/clients
$access_token = null;
// Get your "Creator's Refesh Token" from https://www.patreon.com/platform/documentation/clients
$refresh_token = null;
$api_client = new Patreon\API($access_token);

// If the token doesn't work, get a newer one
if ($campaign_response['errors']) {
    // Make an OAuth client
    // Get your Client ID and Secret from https://www.patreon.com/platform/documentation/clients
    $client_id = null;
    $client_secret = null;
    $oauth_client = new Patreon\OAuth($client_id, $client_secret);
    // Get a fresher access token
    $tokens = $oauth_client->refresh_token($refresh_token, null);
    if ($tokens['access_token']) {
        $access_token = $tokens['access_token'];
        echo "Got a new access_token! Please overwrite the old one in this script with: " . $access_token . " and try again.";
    } else {
        echo "Can't recover from access failure\n";
        print_r($tokens);
    }
    return;
}
?>

Request [7]

POST api.patreon.com/oauth2/token
    ?grant_type=refresh_token
    &refresh_token=<the user‘s refresh_token>
    &client_id=<your client id>
    &client_secret=<your client secret>

which will return a JSON response of:

{
    "access_token": <single use token>,
    "refresh_token": <single use token>,
    "expires_in": <token lifetime duration>,
    "scope": <token scopes>,
    "token_type": "Bearer"
}

and you should store this information just as before.

Tokens are valid for up to one month after they are issued. During this period, you may refresh a user’s information using the API calls from step 4. If you wish to get up-to-date information after the token has expired, a new token may be issued to be used for the following month. To refresh a token,

API

To use a given access_token, send it in an HTTP Header as follows:

Authorization: Bearer <user's access_token>

Our JSON responses will follow the JSON-API standard, with the following structure for our three main resources (users, campaigns, and pledges):

User Object Structure:

{
  "type": "user"
  "id": <string>
  "attributes": {
    "first_name": <string>
    "last_name": <string>
    "full_name": <string>
    "vanity": <string>
    "email": <string>
    "about": <string>
    "facebook_id": <string>
    "image_url": <string>
    "thumb_url": <string>
    "youtube": <string>
    "twitter": <string>
    "facebook": <string>
    "created": <date>
    "url": <string>
  }
  "relationships": {
    "campaign": ...<campaign>...
  }
}

Campaign Object Structure:

{
  "type": "campaign"
  "id": <string>
  "attributes": {
    "summary": <string>
    "creation_name": <string>
    "pay_per_name": <string>
    "one_liner": <string>
    "main_video_embed": <string>
    "main_video_url": <string>
    "image_small_url": <string>
    "image_url": <string>
    "thanks_video_url": <string>
    "thanks_embed": <string>
    "thanks_msg": <string>
    "is_monthly": <bool>
    "is_nsfw": <bool>
    "created_at": <date>
    "published_at": <date>
    "pledge_url": <string>
    "pledge_sum": <int>
    "patron_count": <int>
    "creation_count": <int>
    "outstanding_payment_amount_cents": <int>
  }
  "relationships": {
    "creator": ...<user>...
    "rewards": [ ...<reward>, <reward>, ... ]
    "goals": [ ...<goal>, <goal>, ... ]
    "pledges": [ ...<pledge>, <pledge>, ... ]
  }
}

Pledge Object Structure

{
  "type": "pledge"
  "id": <string>
  "attributes": {
    "amount_cents": <int>
    "created_at": <date>
    "pledge_cap_cents": <int>
    "patron_pays_fees": <bool>
  }
  "relationships": {
    "patron": ...<user>...
    "reward": ...<reward>...
    "creator": ...<user>...
    "address": ...<address>...
    "card": ...<card>...
    "pledge_vat_location": ...<vat-location>...
  }
}

Presently, there are three APIs available:

• Fetching your own profile and campaign info
• Paging through a list of pledges to you
• Fetching a patron's profile info

These APIs are accessed using an OAuth client access_token obtained from the Clients & API Keys page. Please go there first if you do not yet have one.

When performing an API request, the information you are allowed to see is determined by which access_token you are using. Please be sure to select your access_token appropriately. For example, if someone has granted your OAuth client access to their profile information, and you try to fetch it using your own access_token instead of the one created when they granted your client access, you will instead just get your own profile information.

Fetch your own profile and campaign info

require 'patreon'

class OAuthController < ApplicationController
  def redirect
    oauth_client = Patreon::OAuth.new(client_id, client_secret)
    tokens = oauth_client.get_tokens(params[:code], redirect_uri)
    access_token = tokens['access_token']

    api_client = Patreon::API.new(access_token)
    user_response = api_client.fetch_user()
    @user = user_response['data']
    included = user_response['included']
    if included
      @pledge = included.find {|obj| obj['type'] == 'pledge' && obj['relationships']['creator']['data']['id'] == creator_id}
      @campaign = included.find {|obj| obj['type'] == 'campaign' && obj['relationships']['creator']['data']['id'] == creator_id}
    else
      @pledge = nil
      @campaign = nil
    end
  end
end

<?php

require_once('vendor/patreon/patreon/src/patreon.php');

use Patreon\API;
use Patreon\OAuth;

$client_id = null;      // Replace with your data
$client_secret = null;  // Replace with your data
$creator_id = null;     // Replace with your data

$oauth_client = new Patreon\OAuth($client_id, $client_secret);

// Replace http://localhost:5000/oauth/redirect with your own uri
$redirect_uri = "http://localhost:5000/oauth/redirect";
// Make sure that you're using this snippet as Step 2 of the OAuth flow: https://www.patreon.com/platform/documentation/oauth
// so that you have the 'code' query parameter.
$tokens = $oauth_client->get_tokens($_GET['code'], $redirect_uri);
$access_token = $tokens['access_token'];
$refresh_token = $tokens['refresh_token'];

$api_client = new Patreon\API($access_token);
$patron_response = $api_client->fetch_user();
$patron = $patron_response['data'];
$included = $patron_response['included'];
$pledge = null;
if ($included != null) {
  foreach ($included as $obj) {
    if ($obj["type"] == "pledge" && $obj["relationships"]["creator"]["data"]["id"] == $creator_id) {
      $pledge = $obj;
      break;
    }
  }
}

/*
 $patron will have the authenticated user's user data, and
 $pledge will have their patronage data.
 Typically, you will save the relevant pieces of this data to your database,
 linked with their user account on your site,
 so your site can customize its experience based on their Patreon data.
 You will also want to save their $access_token and $refresh_token to your database,
 linked to their user account on your site,
 so that you can refresh their Patreon data on your own schedule.
 */

?>

import patreon
from flask import request
...

client_id = None      # Replace with your data
client_secret = None  # Replace with your data
creator_id = None     # Replace with your data

@app.route('/oauth/redirect')
def oauth_redirect():
    oauth_client = patreon.OAuth(client_id, client_secret)
    tokens = oauth_client.get_tokens(request.args.get('code'), '/oauth/redirect')
    access_token = tokens['access_token']

    api_client = patreon.API(access_token)
    user_response = api_client.fetch_user()
    user = user_response['data']
    included = user_response.get('included')
    if included:
        pledge = next((obj for obj in included
            if obj['type'] == 'pledge' and obj['relationships']['creator']['data']['id'] == creator_id), None)
        campaign = next((obj for obj in included
            if obj['type'] == 'campaign' and obj['relationships']['creator']['data']['id'] == creator_id), None)
    else:
        pledge = None
        campaign = None

curl "http://example.com/api/kittens"
  -H "Authorization: meowmeowmeow"

import url from 'url'
import patreonAPI, { oauth as patreonOAuth } from 'patreon'

const CLIENT_ID = 'pppp'
const CLIENT_SECRET = 'pppp'
const patreonOAuthClient = patreonOAuth(CLIENT_ID, CLIENT_SECRET)

const redirectURL = 'http://mypatreonapp.com/oauth/redirect'

function handleOAuthRedirectRequest(request, response) {
    const oauthGrantCode = url.parse(request.url, true).query.code

    patreonOAuthClient.getTokens(oauthGrantCode, redirectURL, (tokensError, { access_token }) => {
        const patreonAPIClient = patreonAPI(access_token)

        patreonAPIClient(`/current_user`, (currentUserError, apiResponse) => {
            if (currentUserError) {
                console.error(currentUserError)
                response.end(currentUserError)
            }

            response.end(apiResponse);
        })
    })
})

import com.patreon.OAuth;
import com.patreon.API;
import org.json.JSONObject;
import org.json.JSONArray;
...

String clientID = null;        // Replace with your data
String clientSecret = null;    // Replace with your data
String creatorID = null;       // Replace with your data
String redirectURI = null;     // Replace with your data
String code = null;            // get from inbound HTTP request

OAuth oauthClient = new OAuth(clientID, clientSecret);
JSONObject tokens = oauthClient.getTokens(code, redirectURI);
String accessToken = tokens.getString("access_token");

API apiClient = new API(accessToken);
JSONObject userResponse = apiClient.fetchUser();
JSONObject user = userResponse.getJSONObject("data");
JSONArray included = userResponse.getJSONArray("included");
JSONObject pledge = null;
JSONObject campaign = null;
if (included != null) {
   for (int i = 0; i < included.length(); i++) {
       JSONObject object = included.getJSONObject(i);
       if (object.getString("type").equals("pledge") && object.getJSONObject("relationships").getJSONObject("creator").getJSONObject("data").getString("id").equals(creatorID)) {
           pledge = object;
           break;
       }
   }
   for (int i = 0; i < included.length(); i++) {
       JSONObject object = included.getJSONObject(i);
       if (object.getString("type").equals("campaign") && object.getJSONObject("relationships").getJSONObject("creator").getJSONObject("data").getString("id").equals(creatorID)) {
           campaign = object;
           break;
       }
   }
}

   // use the user, pledge, and campaign objects as you desire

The above command returns JSON structured like this:

{
  "type": "user"
  "id": <string>
  "attributes": {
    "first_name": <string>
    "last_name": <string>
    "full_name": <string>
    "vanity": <string>
    "email": <string>
    "about": <string>
    "facebook_id": <string>
    "image_url": <string>
    "thumb_url": <string>
    "youtube": <string>
    "twitter": <string>
    "facebook": <string>
    "is_suspended": <bool>
    "is_deleted": <bool>
    "is_nuked": <bool>
    "created": <date>
    "url": <string>
  }
  "relationships": {
    "campaign": ...<campaign>...
  }
}

This endpoint returns a JSON representation of the user's campaign, including its rewards and goals, and the pledges to it. If there are more than twenty pledges to the campaign, the first twenty will be returned, along with a link to the next page of pledges.

HTTP Request

GET https://api.patreon.com/oauth2/api/current_user/campaigns

Query Parameters

Parameter	Default	Description
includes	rewards,creator,goals,pledge	You can pass this rewards, creator, goals, or pledge

Paging through a list of pledges to you

api_client = patreon.API(patron_access_token)
patrons_page = api_client.fetch_page_of_pledges(campaign_id, 10)
next_cursor = api_client.extract_cursor(patrons_page)
second_patrons_page = api_client.fetch_page_of_pledges(campaign_id, 10, cursor=next_cursor)

api_client = patreon.API(patron_access_token)
patrons_page = api_client.fetch_page_of_pledges(campaign_id, 10)
next_cursor = api_client.extract_cursor(patrons_page)
second_patrons_page = api_client.fetch_page_of_pledges(campaign_id, 10, cursor=next_cursor)

// TODO: Needs a code example of pagination

curl "http://example.com/api/kittens"
  -H "Authorization: meowmeowmeow"

// TODO: Add paginated example

<?php
require_once('vendor/patreon/patreon/src/patreon.php');
use Patreon\API;
use Patreon\OAuth;
$access_token = **Your access token**;
$api_client = new Patreon\API($access_token);
// get page after page of pledge data
$campaign_id = $campaign_response['data'][0]['id'];
$cursor = null;
while (true) {
    $pledges_response = $api_client->fetch_page_of_pledges($campaign_id, 25, $cursor);
    // get all the users in an easy-to-lookup way
    $user_data = [];
    foreach ($pledges_response['included'] as $included_data) {
        if ($included_data['type'] == 'user') {
            $user_data[$included_data['id']] = $included_data;
        }
    }
    // loop over the pledges to get e.g. their amount and user name
    foreach ($pledges_response['data'] as $pledge_data) {
        $pledge_amount = $pledge_data['attributes']['amount_cents'];
        $patron_id = $pledge_data['relationships']['patron']['data']['id'];
        $patron_full_name = $user_data[$patron_id]['attributes']['full_name'];
        echo $patron_full_name . " is pledging " . $pledge_amount . " cents.\n";
    }
    // get the link to the next page of pledges
    $next_link = $pledges_response['links']['next'];
    if (!$next_link) {
        // if there's no next page, we're done!
        break;
    }
    // otherwise, parse out the cursor param
    $next_query_params = explode("?", $next_link)[1];
    parse_str($next_query_params, $parsed_next_query_params);
    $cursor = $parsed_next_query_params['page']['cursor'];
}
echo "Done!";
?>

The above command returns JSON structured like this:

{
  "type": "user"
  "id": <string>
  "attributes": {
    "first_name": <string>
    "last_name": <string>
    "full_name": <string>
    "vanity": <string>
    "email": <string>
    "about": <string>
    "facebook_id": <string>
    "image_url": <string>
    "thumb_url": <string>
    "youtube": <string>
    "twitter": <string>
    "facebook": <string>
    "is_suspended": <bool>
    "is_deleted": <bool>
    "is_nuked": <bool>
    "created": <date>
    "url": <string>
  }
  "relationships": {
    "campaign": ...<campaign>...
  }
}

This API returns a JSON list of pledges to the provided campaign_id. They are sorted by the date the pledge was made, and provide relationship references to the users who made each respective pledge.

The API response will also contain a links section which may be used to fetch the next page of pledges, or go back to the first page.

HTTP Request

GET https://api.patreon.com/oauth2/api/campaigns/<campaign_id>/pledges

Paging

You may only fetch your own list of pledges. If you attempt to fetch another creator's pledge list, the API call will return an HTTP 403. If you would like to create an application which can manage many creator's campaigns, please contact us at [email protected].

Fetching a patron's profile info

require 'patreon'

class OAuthController < ApplicationController
  def redirect
    oauth_client = Patreon::OAuth.new(client_id, client_secret)
    tokens = oauth_client.get_tokens(params[:code], redirect_uri)
    access_token = tokens['access_token']

    api_client = Patreon::API.new(access_token)
    user_response = api_client.fetch_user()
    @user = user_response['data']
    included = user_response['included']
    if included
      @pledge = included.find {|obj| obj['type'] == 'pledge' && obj['relationships']['creator']['data']['id'] == creator_id}

    else
      @pledge = nil
    end
  end
end

import patreon
from flask import request
...

client_id = None      # Replace with your data
client_secret = None  # Replace with your data
creator_id = None     # Replace with your data

@app.route('/oauth/redirect')
def oauth_redirect():
    oauth_client = patreon.OAuth(client_id, client_secret)
    tokens = oauth_client.get_tokens(request.args.get('code'), '/oauth/redirect')
    access_token = tokens['access_token']

    api_client = patreon.API(access_token)
    user_response = api_client.fetch_user()
    user = user_response['data']
    included = user_response.get('included')
    if included:
        pledge = next((obj for obj in included
            if obj['type'] == 'pledge' and obj['relationships']['creator']['data']['id'] == creator_id), None)
    else:
        pledge = None

curl "http://example.com/api/kittens"
  -H "Authorization: meowmeowmeow"

<?php

require_once('vendor/patreon/patreon/src/patreon.php');

use Patreon\API;
use Patreon\OAuth;

$client_id = null;      // Replace with your data
$client_secret = null;  // Replace with your data
$creator_id = null;     // Replace with your data

$oauth_client = new Patreon\OAuth($client_id, $client_secret);

// Replace http://localhost:5000/oauth/redirect with your own uri
$redirect_uri = "http://localhost:5000/oauth/redirect";
// Make sure that you're using this snippet as Step 2 of the OAuth flow: https://www.patreon.com/platform/documentation/oauth
// so that you have the 'code' query parameter.
$tokens = $oauth_client->get_tokens($_GET['code'], $redirect_uri);
$access_token = $tokens['access_token'];
$refresh_token = $tokens['refresh_token'];

$api_client = new Patreon\API($access_token);
$patron_response = $api_client->fetch_user();
$patron = $patron_response['data'];
$included = $patron_response['included'];
$pledge = null;
if ($included != null) {
  foreach ($included as $obj) {
    if ($obj["type"] == "pledge" && $obj["relationships"]["creator"]["data"]["id"] == $creator_id) {
      $pledge = $obj;
      break;
    }
  }
}

/*
 $patron will have the authenticated user's user data, and
 $pledge will have their patronage data.
 Typically, you will save the relevant pieces of this data to your database,
 linked with their user account on your site,
 so your site can customize its experience based on their Patreon data.
 You will also want to save their $access_token and $refresh_token to your database,
 linked to their user account on your site,
 so that you can refresh their Patreon data on your own schedule.
 */

?>

import url from 'url'
import patreonAPI, { oauth as patreonOAuth } from 'patreon'

const CLIENT_ID = 'pppp'
const CLIENT_SECRET = 'pppp'
const patreonOAuthClient = patreonOAuth(CLIENT_ID, CLIENT_SECRET)

const redirectURL = 'http://mypatreonapp.com/oauth/redirect'

function handleOAuthRedirectRequest(request, response) {
    const oauthGrantCode = url.parse(request.url, true).query.code

    patreonOAuthClient.getTokens(oauthGrantCode, redirectURL, (tokensError, { access_token }) => {
        const patreonAPIClient = patreonAPI(access_token)

        patreonAPIClient(`/current_user`, (currentUserError, apiResponse) => {
            if (currentUserError) {
                console.error(currentUserError)
                response.end(currentUserError)
            }

            response.end(apiResponse);
        })
    })
})

import com.patreon.OAuth;
import com.patreon.API;
import org.json.JSONObject;
import org.json.JSONArray;
...

String clientID = null;        // Replace with your data
String clientSecret = null;    // Replace with your data
String creatorID = null;       // Replace with your data
String redirectURI = null;     // Replace with your data
String code = null;            // get from inbound HTTP request

OAuth oauthClient = new OAuth(clientID, clientSecret);
JSONObject tokens = oauthClient.getTokens(code, redirectURI);
String accessToken = tokens.getString("access_token");

API apiClient = new API(accessToken);
JSONObject userResponse = apiClient.fetchUser();
JSONObject user = userResponse.getJSONObject("data");
JSONArray included = userResponse.getJSONArray("included");
JSONObject pledge = null;
if (included != null) {
   for (int i = 0; i < included.length(); i++) {
       JSONObject object = included.getJSONObject(i);
       if (object.getString("type").equals("pledge") && object.getJSONObject("relationships").getJSONObject("creator").getJSONObject("data").getString("id").equals(creatorID)) {
           pledge = object;
           break;
       }
   }
}

   // use the user, pledge, and campaign objects as you desire

The above command returns JSON structured like this:

{
  "type": "user"
  "id": <string>
  "attributes": {
    "first_name": <string>
    "last_name": <string>
    "full_name": <string>
    "vanity": <string>
    "email": <string>
    "about": <string>
    "facebook_id": <string>
    "image_url": <string>
    "thumb_url": <string>
    "youtube": <string>
    "twitter": <string>
    "facebook": <string>
    "is_suspended": <bool>
    "is_deleted": <bool>
    "is_nuked": <bool>
    "created": <date>
    "url": <string>
  }
  "relationships": {
      ...
  }
}

This API returns a JSON representation of the user who granted your OAuth client the provided access_token. It is most typically used in the OAuth "Log in with Patreon flow" to create or update the user's account on your site.

HTTP Request

GET https://api.patreon.com/oauth2/api/current_user

Query Parameters

Parameter	Default	Description
includes	rewards,creator,goals,pledge	You can pass this rewards, creator, goals, or pledge

Webhooks

Webhooks use the permissions provided by specific OAuth clients obtained from the Clients & API Keys page. Please go there first to set up your OAuth client.

Webhooks allow you to receive real-time updates from our servers. While there will eventually be many events about which you can be notified, we presently only support webhooks that trigger when you get a new patron, or an existing patron edits or deletes their pledge.

When one of these events occurs, our servers will send an HTTP POST to a URL you specify. This HTTP POST will contain the relevant data from the user action in JSON format. It will also have headers

X-Patreon-Event: [trigger]
X-Patreon-Signature: [message signature]

where the message signature is the JSON POST body HMAC signed (with MD5) with your client_secret.

Note: As always: please never reveal your client_secrets. If the secret is compromised, the attacker could get access to your campaign info, all of your patron’s profile info, and their pledge amounts (all on an ongoing, refreshable basis). If you fear your secret has been compromised, please let us know and we will look into granting you a new id & secret pair (this will, however, cause all of your patrons to have to re-“Log in with Patreon”)

Setting up a webhook

Once you've set up a client and API key, you can create new webhook urls here ```json

Webhook payload { "data": { "attributes": { "amount_cents": 250, "created_at": "2015-05-18T23:50:42+00:00", "declined_since": null, "patron_pays_fees": false, "pledge_cap_cents": null }, "id": "1", "relationships": { "address": { "data": null }, "card": { "data": null }, "creator": { "data": { "id": "3024102", "type": "user" }, "links": { "related": "https://www.patreon.com/api/user/3024102" } }, "patron": { "data": { "id": "32187", "type": "user" }, "links": { "related": "https://www.patreon.com/api/user/32187" } }, "reward": { "data": { "id": "599336", "type": "reward" }, "links": { "related": "https://www.patreon.com/api/rewards/599336" } } }, "type": "pledge" }, "included": [ { *** Creator Object *** }, { *** Patron Object *** }, { *** Reward Object *** }, ] } ```

External Services

We have an ever expanding set of external services that enable creators to manage and reward patrons in a flexible way.

Zapier

Zapier is an automation tool that connects your favorite apps, such as Gmail, Slack, MailChimp, and over 750 more. You can use the Patreon Zapier plugin to automate repetitive tasks without coding or relying on developers to build the integration.

It's perfect for many of the use cases that would ordinarily require webhooks and has an ever expanding set of use cases. https://zapier.com/zapbook/patreon/

Use cases

• Track new patrons in Sales Force
• Get notified on slack when a new patron joins or leaves
• Add new patron's contact info to a google sheet
• Sync new patrons with a Mailchimp, Hubspot, ConvertKit, Drip, InfusionSoft, etc.

Our Zapier plugin currently supports pledge activity (adds, updates and deletes). We plan to add more triggers in the future. If you would like to request a trigger, send the request to [email protected].

Wordpress

We have a wordpress plugin that allows creators to gate content on their wordpress page to patrons only. For more information check it out.

Errors

The Patreon API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request sucks.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested is hidden for administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The resource requested has been removed from our servers.
429	Too Many Requests -- Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.