NAV Navbar
shell javascript python ruby php java
  • Introduction
  • API Libraries
  • Third Party Libraries
  • Clients and API Keys
  • OAuth
  • Resources
  • API
  • Calling the API
  • Webhooks
  • External Services
  • Errors
  • FAQs
  • Introduction

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

    Want more than a reference? For a broader overview and use cases, check our our developer portal.

    If you find any errors in this document, do not hesitate to submit an issue or a pull request github repo.

    API Libraries

    We've written some open source libraries to help you use our platform services. Our API follows the JSON:API spec which is pretty complex and these libraries make it a bit easier to work with.

    Javascript

    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

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

    Get the artifact from

    Maven

    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 authenticate with OAuth and interact with the Patreon API, you'll have to register your Client(s). This involves signing up on patreon.com and making a creator account.

    Register your client here

    Once you've registered a Client you'll have access to a:

    OAuth

    Patreon has an OAuth provider service — the technology that lets you log in to Medium with Twitter, log in to Disqus with Google+, and even login to Patreon with Facebook.

    Below, you’ll find steps explaining how to begin integrating with us. It assumes understanding in HTTP protocol and OAuth, and that you have administrative access & developer control of the server that you wish to integrate with Patreon.

    Step 1 - Registering Your Client

    To set up OAuth, you will need to register your client application on the Clients & API Keys page.

    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 OAuth grant type. Set this 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. It will be displayed to the user in human-friendly terms when signing in with Patreon. If your client requires the ability to ask for pledges or campaign data of other users (not just your own campaign), please email [email protected], and we'll do our best to get back to you shortly.
    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):

    Query Parameters

    Parameter Description
    code Used to fetch access tokens for the session that just signed in with Patreon.
    state Trasnparently appended from the state param you provided in your initial link in Step 2.

    Step 4 - Validating Receipt of the OAuth Token

    Request [4]

    POST www.patreon.com/api/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/portal/registration/register-clients
    $access_token = null;
    // Get your "Creator's Refesh Token" from https://www.patreon.com/portal/registration/register-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/portal/registration/register-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 www.patreon.com/api/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, make a POST request to the token endpoint with a grant type of refresh_token, as in the example. You may also manually refresh the token on the appropriate client in your clients page.

    Resources

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

    User

    {
      "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>
        // optional properties
        "like_count": <int>
        "comment_count": <int>
      }
      "relationships": {
        "campaign": ...<campaign>...
      }
    }
    

    Campaign

    {
      "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

    {
      "type": "pledge"
      "id": <string>
      "attributes": {
        "amount_cents": <int>
        "created_at": <date>
        "declined_since": <date>
        "pledge_cap_cents": <int>
        "patron_pays_fees": <bool>
        // optional properties
        "total_historical_amount_cents": <int>
        "is_paused": <bool>
        "has_shipping_address": <bool>
        "outstanding_payment_amount_cents": <int>
      }
      "relationships": {
        "patron": ...<user>...
        "reward": ...<reward>...
        "creator": ...<user>...
        "address": ...<address>...
      }
    }
    

    API

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

    Authorization: Bearer <access_token>
    

    The three endpoints below are accessed using an OAuth client access_token obtained from the OAuth section. Please go there first if you do not yet have one.

    When performing an API request, the information you are allowed 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 Creator's Access Token instead of the one created when they granted your client access, you will instead just get your own profile information.

    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
        @pledge = @user.pledges ? @user.pledges[0] : nil
      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()
        pledges = user.relationship('pledges')
        pledge = pledges[0] if pledges and len(pledges) > 0 else None
    
    curl --request GET \
      --url https://www.patreon.com/api/oauth2/api/current_user \
      --header 'authorization: Bearer <access_token>'
    
    <?php
    
    use Patreon\API;
    use Patreon\OAuth;
    
    $client_id = null;      // Replace with your data
    $client_secret = null;  // Replace with your data
    $redirect_uri = null;   // Replace with your data
    
    $oauth_client = new Patreon\OAuth($client_id, $client_secret);
    $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->get('data');
    $pledge = null;
    if ($patron->has('relationships.pledges')) {
        $pledge = $patron->relationship('pledges')->get(0)->resolve($patron_response);
    }
    
    ?>
    
    import url from 'url'
    import patreonAPI, { oauth as patreonOAuth } from 'patreon'
    
    const CLIENT_ID = null     // Replace with your data
    const CLIENT_SECRET = null // Replace with your data
    const redirectURL = null   // Replace with your data
    
    const patreonOAuthClient = patreonOAuth(CLIENT_ID, CLIENT_SECRET)
    
    function handleOAuthRedirectRequest(request, response) {
        const oauthGrantCode = url.parse(request.url, true).query.code
    
        patreonOAuthClient
            .getTokens(oauthGrantCode, redirectURL)
            .then(tokensResponse => {
                const patreonAPIClient = patreonAPI(tokensResponse.access_token)
                return patreonAPIClient('/current_user')
            })
            .then(({ store }) => {
                response.end(store.findAll('user').map(user => user.serialize()))
            })
            .catch(err => {
                console.error('error!', err)
                response.end(err)
            })
    }
    
    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
    

    Response:

    {
      "data": {
        "attributes": {
          "about": null,
          "created": "2017-10-20T21:36:23+00:00",
          "discord_id": null,
          "email": "[email protected]",
          "facebook": null,
          "facebook_id": null,
          "first_name": "Corgi",
          "full_name": "Corgi The Dev",
          "gender": 0,
          "has_password": true,
          "image_url": "https://c8.patreon.com/2/400/0000000",
          "is_deleted": false,
          "is_email_verified": false,
          "is_nuked": false,
          "is_suspended": false,
          "last_name": "The Dev",
          "social_connections": {
            "deviantart": null,
            "discord": null,
            "facebook": null,
            "spotify": null,
            "twitch": null,
            "twitter": null,
            "youtube": null
          },
          "thumb_url": "https://c8.patreon.com/2/100/0000000",
          "twitch": null,
          "twitter": null,
          "url": "https://www.patreon.com/corgithedev",
          "vanity": "corgithedev",
          "youtube": null
        },
        "id": "0000000",
        "relationships": {
          "pledges": {
            "data": []
          }
        },
        "type": "user"
      },
      "links": {
        "self": "https://www.patreon.com/api/user/0000000"
      }
    }
    

    This endpoint returns a JSON representation of the user who granted your OAuth client an access_token. It is most typically used in the OAuth "Log in with Patreon flow" to create or update the patron's account info in your application.

    HTTP Request

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

    Query Parameters

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

    Fetch a creator profile and campaign info

    require 'patreon'
    
    access_token = nil  # Replace with your data
    
    api_client = Patreon::API.new(access_token)
    campaign_response = api_client.fetch_campaign()
    campaign = campaign_response.data[0]
    puts "campaign is", campaign
    user = campaign.creator
    puts "user is", user
    
    <?php
    
    use Patreon\API;
    use Patreon\OAuth;
    
    $access_token = null;   // Replace with your data
    
    $api_client = new Patreon\API($access_token);
    $campaign_response = $api_client->fetch_campaign();
    $campaign = $campaign_response->get('data')->get('0');
    echo "campaign is\n";
    print_r($campaign->asArray(true));
    $user = $campaign->relationship('creator')->resolve($campaign_response);
    echo "user is\n";
    print_r($user->asArray(true));
    
    import patreon
    
    access_token = None   # Replace with your creator access token
    
    api_client = patreon.API(access_token)
    campaign_response = api_client.fetch_campaign()
    campaign = campaign_response.data()[0]
    print('campaign is', campaign)
    user = campaign.relationship('creator')
    print('user is', user)
    
    curl --request GET \
      --url https://www.patreon.com/api/oauth2/api/current_user/campaigns \
      --header 'Authorization: Bearer <access_token>'
    
    import patreonAPI from 'patreon'
    
    const accessToken = null   // Replace with your creator access token
    
    const patreonAPIClient = patreonAPI(accessToken)
    patreonAPIClient('/current_user/campaigns')
        .then(({ store }) => {
            const user = store.findAll('user').map(user => user.serialize())
            console.log('user is', user)
            const campaign = store.findAll('campaign').map(campaign => campaign.serialize())
            console.log('campaign is', campaign)
        })
        .catch(err => {
            console.error('error!', err)
            response.end(err)
        })
    
    import com.patreon.OAuth;
    import com.patreon.API;
    import org.json.JSONObject;
    import org.json.JSONArray;
    ...
    
    String accessToken = null; // Replace with your data
    
    API apiClient = new API(accessToken);
    JSONObject campaignResponse = apiClient.fetchCampaign();
    JSONObject campaign = campaignResponse.getJSONObject("data");
    JSONArray included = userResponse.getJSONArray("included");
    JSONObject user = null;
    // This will get simplified in future versions of the library.
    // For now, we must denormalize the JSON:API response by hand.
    String userID = campaign .getJSONObject("relationships").getJSONObject("creator").getJSONObject("data").getString("id");
    if (included != null) {
       for (int i = 0; i < included.length(); i++) {
           JSONObject object = included.getJSONObject(i);
           if (object.getString("type").equals("user") && object.getJSONObject("relationships").getJSONObject("creator").getJSONObject("data").getString("id").equals(userID)) {
               user = object;
               break;
           }
       }
    }
    

    Response:

    {
      "data": [{
        "attributes": {
          "created_at": "2017-10-20T21:39:01+00:00",
          "creation_count": 0,
          "creation_name": "Documentation",
          "discord_server_id": null,
          "display_patron_goals": false,
          "earnings_visibility": "public",
          "image_small_url": null,
          "image_url": null,
          "is_charged_immediately": false,
          "is_monthly": false,
          "is_nsfw": false,
          "is_plural": false,
          "main_video_embed": null,
          "main_video_url": null,
          "one_liner": null,
          "outstanding_payment_amount_cents": 0,
          "patron_count": 0,
          "pay_per_name": null,
          "pledge_sum": 0,
          "pledge_url": "/bePatron?c=0000000",
          "published_at": "2017-10-20T21:49:31+00:00",
          "summary": null,
          "thanks_embed": null,
          "thanks_msg": null,
          "thanks_video_url": null
        },
        "id": "0000000",
        "relationships": {
          "creator": {
            "data": {
              "id": "1111111",
              "type": "user"
            },
            "links": {
              "related": "https://www.patreon.com/api/user/1111111"
            }
          },
          "goals": {
            "data": []
          },
          "rewards": {
            "data": [{
                "id": "-1",
                "type": "reward"
              },
              {
                "id": "0",
                "type": "reward"
              }
            ]
          }
        },
        "type": "campaign"
      }],
      "included": [{
          "attributes": {
            "about": null,
            "created": "2017-10-20T21:36:23+00:00",
            "discord_id": null,
            "email": "[email protected]",
            "facebook": null,
            "facebook_id": null,
            "first_name": "Corgi",
            "full_name": "Corgi The Dev",
            "gender": 0,
            "has_password": true,
            "image_url": "https://c8.patreon.com/2/400/1111111",
            "is_deleted": false,
            "is_email_verified": false,
            "is_nuked": false,
            "is_suspended": false,
            "last_name": "The Dev",
            "social_connections": {
              "deviantart": null,
              "discord": null,
              "facebook": null,
              "spotify": null,
              "twitch": null,
              "twitter": null,
              "youtube": null
            },
            "thumb_url": "https://c8.patreon.com/2/100/1111111",
            "twitch": null,
            "twitter": null,
            "url": "https://www.patreon.com/drkthedev",
            "vanity": "drkthedev",
            "youtube": null
          },
          "id": "1111111",
          "relationships": {
            "campaign": {
              "data": {
                "id": "0000000",
                "type": "campaign"
              },
              "links": {
                "related": "https://www.patreon.com/api/campaigns/0000000"
              }
            }
          },
          "type": "user"
        },
        {
          "attributes": {
            "amount": 0,
            "amount_cents": 0,
            "created_at": null,
            "description": "Everyone",
            "id": "-1",
            "remaining": 0,
            "requires_shipping": false,
            "type": "reward",
            "url": null,
            "user_limit": null
          },
          "id": "-1",
          "relationships": {
            "creator": {
              "data": {
                "id": "1111111",
                "type": "user"
              },
              "links": {
                "related": "https://www.patreon.com/api/user/1111111"
              }
            }
          },
          "type": "reward"
        },
        {
          "attributes": {
            "amount": 1,
            "amount_cents": 1,
            "created_at": null,
            "description": "Patrons Only",
            "id": "0",
            "remaining": 0,
            "requires_shipping": false,
            "type": "reward",
            "url": null,
            "user_limit": null
          },
          "id": "0",
          "relationships": {
            "creator": {
              "data": {
                "id": "1111111",
                "type": "user"
              },
              "links": {
                "related": "https://www.patreon.com/api/user/1111111"
              }
            }
          },
          "type": "reward"
        }
      ]
    }
    

    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://www.patreon.com/api/oauth2/api/current_user/campaigns

    Query Parameters

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

    Paging through a list of pledges

    require 'patreon'
    require 'uri'
    require 'cgi'
    
    access_token = nil # your Creator Access Token
    api_client = Patreon::API.new(access_token)
    
    # Get the campaign ID
    campaign_response = api_client.fetch_campaign()
    campaign_id = campaign_response.data[0].id
    
    # Fetch all pledges
    all_pledges = []
    cursor = nil
    while true do
        page_response = api_client.fetch_page_of_pledges(campaign_id, 25, cursor)
        all_pledges += page_response.data
        next_page_link = page_response.links[page_response.data]['next']
        if next_page_link
            parsed_query = CGI::parse(next_page_link)
            cursor = parsed_query['page[cursor]'][0]
        else
            break
        end
    end
    
    # Mapping to all patrons. Feel free to customize as needed.
    # As with all standard Ruby objects, (pledge.methods - Object.methods) will list the available attributes and relationships
    puts all_pledges.map{ |pledge| { full_name: pledge.patron.full_name, amount_cents: pledge.amount_cents } }
    
    import patreon
    
    access_token = nil # your Creator Access Token
    api_client = patreon.API(access_token)
    
    # Get the campaign ID
    campaign_response = api_client.fetch_campaign()
    campaign_id = campaign_response.data()[0].id()
    
    # Fetch all pledges
    all_pledges = []
    cursor = None
    while True:
        pledges_response = api_client.fetch_page_of_pledges(campaign_id, 25, cursor=cursor)
        pledges += pledges_response.data()
        cursor = api_client.extract_cursor(pledges_response)
        if not cursor:
            break
    
    // TODO: Needs a code example of pagination
    
    curl --request GET \
      --url https://www.patreon.com/api/oauth2/api/campaigns/<campaign_id>/pledges?include=patron.null \
      --header 'Authorization: Bearer <access_token>
    
    // TODO: get pagination example
    
    <?php
    
    use Patreon\API;
    use Patreon\OAuth;
    
    $access_token = null; // Your Creator Access Token
    
    $api_client = new Patreon\API($access_token);
    
    // Get your campaign data
    $campaign_response = $api_client->fetch_campaign();
    $campaign_id = $campaign_response->get('data.0.id');
    
    // get page after page of pledge data
    $all_pledges = [];
    $cursor = null;
    while (true) {
        $pledges_response = $api_client->fetch_page_of_pledges($campaign_id, 25, $cursor);
        // loop over the pledges to get e.g. their amount and user name
        foreach ($pledges_response->get('data')->getKeys() as $pledge_data_key) {
            $pledge_data = $pledges_response->get('data')->get($pledge_data_key);
            array_push($all_pledges, $pledge_data);
        }
        // get the link to the next page of pledges
        if (!$pledges_response->has('links.next')) {
            // if there's no next page, we're done!
            break;
        }
        $next_link = $pledges_response->get('links.next');
        // 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'];
    }
    ?>
    

    Response:

    {
        "data": [
            {
                "attributes": {
                    "amount_cents": 100,
                    "created_at": "2016-07-25T20:59:52+00:00",
                    "declined_since": null,
                    "patron_pays_fees": false,
                    "pledge_cap_cents": null
                },
                "id": "2745627",
                "relationships": {
                    "patron": {
                        "data": {
                            "id": "111111",
                            "type": "user"
                        },
                        "links": {
                            "related": "https://www.patreon.com/api/user/111111"
                        }
                    }
                },
                "type": "pledge"
            }
        ],
        "included": [
            {
                "attributes": {
                    "about": "sample about text",
                    "created": "2015-01-15T07:25:51+00:00",
                    "email": "[email protected]",
                    "facebook": null,
                    "first_name": "Foo",
                    "full_name": "Foo Bar",
                    "gender": 1,
                    "image_url": "",
                    "is_email_verified": true,
                    "last_name": "Bar",
                    "social_connections": {
                        "deviantart": null,
                        "discord": null,
                        "facebook": null,
                        "spotify": null,
                        "twitch": null,
                        "twitter": null,
                        "youtube": null
                    },
                    "thumb_url": "",
                    "twitch": null,
                    "twitter": "foo",
                    "url": "https://www.patreon.com/foo",
                    "vanity": "foo",
                    "youtube": null
                },
                "id": "111111",
                "type": "user"
            }
        ],
        "links": {
            "first": "https://www.patreon.com/api/oauth2/api/campaigns/70261/pledges?page%5Bcount%5D=10&sort=created",
            "next": "https://www.patreon.com/api/oauth2/api/campaigns/70261/pledges?page%5Bcount%5D=10&sort=created&page%5Bcursor%5D=2017-08-21T20%3A16%3A49.258893%2B00%3A00"
        },
        "meta": {
            "count": 18
        }
    }
    

    This endpoint 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 field which may be used to fetch the next page of pledges, or go back to the first page.

    HTTP Request

    GET https://www.patreon.com/api/oauth2/api/campaigns/<campaign_id>/pledges?include=patron.null

    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].

    Calling the API

    Requesting specific data

    https://www.patreon.com/api/oauth2/api/campaigns/<campaign_id>/pledges?include=reward&fields[pledge]=total_historical_amount_cents,is_paused
    

    Want to retrieve the patrons for your pledges, or the goals for a given campaign?

    To retrieve specific attributes or relationships other than the defaults, you can pass fields and include parameters respectively, each being comma-separated lists of attributes or resources. You can see which attributes or relationships are requestable on a given resource in the resources section.

    Pagination and sorting

    https://www.patreon.com/api/oauth2/api/campaigns/<campaign_id>/pledges?page[count]=5&sort=-created&page[cursor]=2012-01-19
    

    Our API endpoints support pagination and sorting on some attributes.

    Parameter Description
    page[count] Maximum number of results returned
    sort Comma-separated attributes to sort by, in order of precedence. Each attribute can be prepended with - to indicate descending order. Currently, we support created and modified for pledges.
    page[cursor] From the sorted results, start returning where the first attribute in sort equals this value.

    The example URL on the right is for 5 pledges with max created before 2012-01-19, in reverse chronological order.

    The links field of the response body contains URLs of first, prev, next, and last pages if they exist.

    Webhooks

    Sample 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 ** *
        },
      ]
    }
    

    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.

    By creating a webhook, you can specify a URL for us to send an HTTP POST to when one of these events occur. This POST request 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 HEX digest of the message body HMAC signed (with MD5) using your webhook's secret viewable on the webhooks page. You can use this to verify us as the sender of the message.

    Triggers

    A trigger is an event type. The syntax of a trigger is [resource]:[action] (e.g. pledges:create). You can add or remove triggers for a webhook to listen to on the webhooks page.

    Retry Schedule

    Network conditions and temporary outages mean that sometimes events won't reach your server on the first try. Therefore, we store events so that the data isn't lost, and retry them at a tapering rate over the next month.

    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

    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 -- Something was wrong with your request (syntax, size too large, etc.)
    401 Unauthorized -- Authentication failed (bad API key, invalid OAuth token, incorrect scopes, etc.)
    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 -- Our server ran into a problem while processing this request. Please try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    FAQs

    Testing

    Testing of the API can be done by creating dummy accounts through the website. To test pledging, it can be useful to:

    1. Create a Patreon account with creator page and set it to "per post".
    2. Create another Patreon account and use it to pledge to the first account's page. A "per post" pledge will not incur any payments as long as it is cancelled before the end of the month.
    3. Use the API as needed.