Patreon API

https://docs.patreon.com/
Admin
The Patreon API allows developers to integrate with Patreon's platform, enabling access to creator...
Tokens:43,122
Snippets:230
Trust Score:10
Update:2 days ago
Show doc for...
Tokens:
Raw
### Add patreon to requirements.txt and install

Source: https://docs.patreon.com/

Add patreon to a requirements.txt file and install all dependencies with pip. This is an alternative to direct pip install.

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

--------------------------------

### Example response with next cursor

Source: https://docs.patreon.com/

Example response showing the `meta.pagination.cursors.next` value used to fetch the next page.

```json
{
  "data": {},
  "meta": {
    "pagination": {
      "total": 10,
      "cursors": {
        "next": "03:eyJ2IjoxLCJjIjoiNmY2YWMxMGUtYmU2NS00MTc5LWEyODktMzkwZGMxMTFhMTQ1IiwidCI6IiJ9:1V2dmthW5w5REEsle2scJmOm"
      }
    }
  }
}
```

--------------------------------

### JavaScript: TODO placeholder for pagination example

Source: https://docs.patreon.com/

Placeholder comment indicating that a pagination example is needed.

```javascript
// TODO: get pagination example
```

--------------------------------

### Install Patreon Python library via pip

Source: https://docs.patreon.com/

Install the patreon Python package from PyPI using pip. Ensure dependencies are installed as well.

```bash
pip install patreon
```

--------------------------------

### Install Patreon PHP library via Composer

Source: https://docs.patreon.com/

Install the patreon/patreon PHP package from Packagist using Composer.

```bash
composer require patreon/patreon
```

--------------------------------

### Sample response for GET /api/oauth2/v2/identity with email scope

Source: https://docs.patreon.com/

Example JSON response from the identity endpoint when requesting specific user fields. Shows the user resource with email and full_name attributes, a campaign relationship, and an included campaign object. The response is for a URL-decoded request with fields[user]=about,created,email,first_name,full_name,image_url,last_name,social_connections,thumb_url,url,vanity.

```json
{
    "data": {
        "attributes": {
            "email": "[email protected]",
            "full_name": "Platform Team"
        },
        "id": "id",
        "relationships": {
            "campaign": {
                "data": {
                    "id": "id",
                    "type": "campaign"
                },
                "links": {
                    "related": "https://www.patreon.com/api/oauth2/v2/campaigns/id"
                }
            }
        },
        "type": "user"
    },
    "included": [
        {
            "attributes": {
                "is_monthly": true,
                "summary": "Hi There"
            },
            "id": "id",
            "type": "campaign"
        }
    ],
    "links": {
        "self": "https://www.patreon.com/api/oauth2/v2/user/id"
    }
}
```

--------------------------------

### Python: Paging through pledges with Patreon API

Source: https://docs.patreon.com/

Uses the Patreon Python client to fetch all pledges by iterating through pages. Requires a Creator Access Token. The example uses the extract_cursor method to get the next page cursor.

```python
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
```

--------------------------------

### JavaScript: TODO placeholder for pagination

Source: https://docs.patreon.com/

Placeholder comment indicating that a JavaScript pagination example is needed.

```javascript
// TODO: Needs a code example of pagination
```

--------------------------------

### Webhook payload example

Source: https://docs.patreon.com/

Example JSON payload sent when a webhook fires. Verify the X-Patreon-Signature header to confirm authenticity. The payload includes member data with relationships to campaign and user, and included campaign and user data.

```json
{
  "data": {
    "attributes": {
      "currently_entitled_amount_cents": null,
      "full_name": "Platform",
      "is_follower": true,
      "last_charge_date": null,
      "last_charge_status": null,
      "lifetime_support_cents": 0,
      "note": "",
      "patron_status": null,
      "pledge_relationship_start": null
    },
    "id": "d485d5ac-6c82-42c6-9c08-c50cf01b73d7",
    "relationships": {
      "address": {
        "data": null
      },
      "campaign": {
        "data": {
          "id": "123456",
          "type": "campaign"
        }
      },
      "currently_entitled_tiers": {
        "data": []
      },
      "user": {
        "data": {
          "id": "987654321",
          "type": "user"
        }
      }
    },
    "type": "member"
  },
  "included": [
    ...campaign data...
    ...user data...
  ]
}
```

--------------------------------

### POST /api/oauth2/v2/webhooks - Example Payload and Response

Source: https://docs.patreon.com/

Shows the JSON payload for creating a webhook with triggers and a URI, and the corresponding API response. Requires the w:campaigns.webhook scope.

```json
// Example POST Payload
{
  "data": {
    "type": "webhook",
    "attributes": {
      "triggers": ["members:create", "members:update", "members:delete"],
      "uri": "https://www.example.com",
    },
    "relationships": {
      "campaign": {
        "data": {"type": "campaign", "id": "12345"},
      },
    },
  },
}

// Example API response
{
   "data":{
      "attributes":{
         "last_attempted_at": null,
         "paused":false,
         "num_consecutive_times_failed":0,
         "secret":"abcdefghiklmnopqrstuvwyz",
         "triggers":[
            "members:create",
            "members:update",
            "members:delete"
         ],
         "uri":"https://example.com/hooks/patreon"
      },
      "id":"3955",
      "type":"webhook"
   }
}
```

--------------------------------

### Request optional attributes with fields query param

Source: https://docs.patreon.com/

Example GET request to fetch optional pledge attributes `total_historical_amount_cents` and `is_paused`. Remember to URL-encode square brackets in raw cURL.

```http
GET https://www.patreon.com/api/oauth2/api/campaigns/<campaign_id>/pledges?fields[pledge]=total_historical_amount_cents,is_paused
```

--------------------------------

### Java: Fetch patron profile with OAuth

Source: https://docs.patreon.com/

Uses com.patreon.OAuth and com.patreon.API to get tokens and fetch the user, then finds the pledge for a specific creator from the included array. Requires clientID, clientSecret, creatorID, redirectURI, and code.

```Java
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
```

--------------------------------

### Fetch campaign in Python

Source: https://docs.patreon.com/

Uses the Patreon Python library to fetch campaign data and print the campaign and creator. Requires an access token.

```python
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)
```

--------------------------------

### PHP: Fetch patron profile with OAuth

Source: https://docs.patreon.com/

Uses Patreon\OAuth and Patreon\API to get tokens and fetch the user, then resolves the first pledge relationship. Requires client_id, client_secret, and redirect_uri.

```PHP
<?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);
}

?>
```

--------------------------------

### Fetch campaign in Java

Source: https://docs.patreon.com/

Uses the Patreon Java library to fetch campaign data and manually denormalize the JSON:API response to get the creator user. Requires an access token.

```java
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;
       }
   }
}
```

--------------------------------

### OAuth Redirect GET Request with Query Parameters

Source: https://docs.patreon.com/

The redirect URI receives a GET request with 'code' and 'state' query parameters after the user grants access. The 'code' is a single-use code used to fetch access tokens, and 'state' is transparently appended from the initial link.

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

--------------------------------

### GET /api/oauth2/v2/webhooks

Source: https://docs.patreon.com/

Retrieves a list of webhooks configured for the authenticated client.

```APIDOC
## GET /api/oauth2/v2/webhooks

### Description
Retrieves a list of webhooks configured for the authenticated client.

### Method
GET

### Endpoint
/api/oauth2/v2/webhooks

### Response
#### Success Response (200)
- **data** (array) - List of webhook objects.

#### Response Example
{
  "data": []
}
```

--------------------------------

### GET /api/oauth2/v2/posts/{id}

Source: https://docs.patreon.com/

Retrieves a particular Post by its ID. Requires the campaigns.posts scope.

```APIDOC
## GET /api/oauth2/v2/posts/{id}

### Description
Get a particular Post by ID. Requires the `campaigns.posts` scope.

### Method
GET

### Endpoint
/api/oauth2/v2/posts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the post.

### Response
#### Success Response (200)
- **data** (object) - The Post object.

### Response Example
{
  "data": {}
}
```

--------------------------------

### PHP: Paging through pledges with Patreon API

Source: https://docs.patreon.com/

Uses the Patreon PHP client to fetch all pledges by iterating through pages. Requires a Creator Access Token. The example loops over pledges and extracts the cursor from the next link.

```php
<?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'];
}
?>
```

--------------------------------

### GET /api/oauth2/v2/members/{member_id}

Source: https://docs.patreon.com/

Retrieves a specific member by their ID. This endpoint returns member details.

```APIDOC
## GET /api/oauth2/v2/members/{member_id}

### Description
Retrieves a specific member by their ID.

### Method
GET

### Endpoint
/api/oauth2/v2/members/{member_id}

### Parameters
#### Path Parameters
- **member_id** (string) - Required - The unique identifier of the member.

### Response
#### Success Response (200)
Returns the member details.

#### Response Example
(No example provided in source)
```

--------------------------------

### Fetch campaign in Ruby

Source: https://docs.patreon.com/

Uses the Patreon Ruby gem to fetch campaign data and print the campaign and creator. Requires an access token.

```ruby
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
```

--------------------------------

### GET /api/oauth2/v2/posts/{id}

Source: https://docs.patreon.com/

Retrieves a specific post by its ID. This endpoint returns post details.

```APIDOC
## GET /api/oauth2/v2/posts/{id}

### Description
Retrieves a specific post by its ID.

### Method
GET

### Endpoint
/api/oauth2/v2/posts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the post.

### Response
#### Success Response (200)
Returns the post details.

#### Response Example
(No example provided in source)
```

--------------------------------

### Python: Fetch patron profile with Flask

Source: https://docs.patreon.com/

Uses the 'patreon' library in a Flask route to get tokens from the OAuth code, fetch the user, and access their pledges. Requires client_id, client_secret, and creator_id to be set.

```Python
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
```

--------------------------------

### Fetch campaign in PHP

Source: https://docs.patreon.com/

Uses the Patreon PHP library to fetch campaign data and print the campaign and creator. Requires an access token.

```php
<?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));
```

--------------------------------

### GET /api/oauth2/v2/campaigns

Source: https://docs.patreon.com/

Retrieves a list of campaigns for the authenticated user. This endpoint returns campaign data.

```APIDOC
## GET /api/oauth2/v2/campaigns

### Description
Retrieves a list of campaigns for the authenticated user.

### Method
GET

### Endpoint
/api/oauth2/v2/campaigns

### Parameters
No parameters documented.

### Response
#### Success Response (200)
Returns a list of campaigns.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/oauth2/v2/identity

Source: https://docs.patreon.com/

Retrieves the identity of the authenticated user. This endpoint returns the user's profile information.

```APIDOC
## GET /api/oauth2/v2/identity

### Description
Retrieves the identity of the authenticated user.

### Method
GET

### Endpoint
/api/oauth2/v2/identity

### Parameters
No parameters documented.

### Response
#### Success Response (200)
Returns the user's identity information.

#### Response Example
(No example provided in source)
```

--------------------------------

### Ruby: Paging through pledges with Patreon API

Source: https://docs.patreon.com/

Uses the Patreon Ruby client to fetch all pledges by iterating through pages. Requires a Creator Access Token. The example prints each patron's full name and pledge amount in cents.

```ruby
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 } }
```

--------------------------------

### Ruby: Fetch patron profile with OAuth

Source: https://docs.patreon.com/

Uses the 'patreon' gem to get tokens from an OAuth code, then fetches the user and their first pledge. Requires client_id, client_secret, and redirect_uri.

```Ruby
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
```

--------------------------------

### GET /api/oauth2/v2/campaigns/{campaign_id}

Source: https://docs.patreon.com/

Retrieves a specific campaign by its ID. This endpoint returns detailed campaign information.

```APIDOC
## GET /api/oauth2/v2/campaigns/{campaign_id}

### Description
Retrieves a specific campaign by its ID.

### Method
GET

### Endpoint
/api/oauth2/v2/campaigns/{campaign_id}

### Parameters
#### Path Parameters
- **campaign_id** (string) - Required - The unique identifier of the campaign.

### Response
#### Success Response (200)
Returns the campaign details.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/oauth2/v2/lives/{id}

Source: https://docs.patreon.com/

Retrieves a specific live event by its ID. This endpoint returns live event details.

```APIDOC
## GET /api/oauth2/v2/lives/{id}

### Description
Retrieves a specific live event by its ID.

### Method
GET

### Endpoint
/api/oauth2/v2/lives/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the live event.

### Response
#### Success Response (200)
Returns the live event details.

#### Response Example
(No example provided in source)
```
Tokens:
Raw