Using Pledge Histories

In some cases, you might need to know not just whether a user is pledged to a particular tier right now but whether they have ever pledged to a tier, or if they were pledged during a specific time period in which you ran an event, etc. For example, you may decide to give a permanent reward to everyone who pledges during January, then even if someone unsubscribes and launches the game in April you want to be able to ensure they are still able to receive that reward.

These scenarios can be supported by fetching the user's pledge history (the history of changes to their pledge status) and searching through it to discover when they were pledged to a given tier.

Scope Notes

In order to request a user's pledge history, it is necessary to to request the identity.memberships scope. By default, when performing authentication only the identity scope is requested, so you must provide the complete list of scopes you need in the Scope Overrides parameter. This is most likely: identity identity.memberships

An important side-effect of enabling the identity.memberships scope is that many API queries will begin returning data not only about your campaign but about all campaigns the user is pledged to! To deal with this, you should pass your Campaign ID to any node which accepts it (e.g. Get Usre Info). This will allow the plugin to filter the data received from Patreon for you and extract only the data relevant to your campaign. An editor utility is provided to make getting your Campaign ID easier.

For more information on the scopes supported by the API, see here: https://docs.patreon.com/#scopes

It is important to note that once a user has authorized the use of a scope, Patreon's API will always process API requests for this user as having this scope (even if in the future you reduce the scopes you request). This means that if you enable the identity.memberships scope then later decide that you don't need it, Patreon will still process requests as if you have requested it. The only way to reduce the scopes the API uses is to create a new API client and migrate your application to the new Client ID.

Best Practices

It is important to be aware that not all actions a subscriber takes which may affect their eligibility for a particular tier or reward are captured in their pledge history. For example, a gifted subscription does not show up in the user's pledge history. This means that if your goal is to answer the question, "Was this user entitled to Tier A during the month of January?", the information in the pledge history cannot give you a definitive answer in all cases. If the user paid for a subscription during January you will be able to see that in their history, but if they were on a gifted subscription, a free member, etc., their pledge history may be empty.

For this reason, to ensure the widest range of cases are covered, it is recommended to always first check the user's current entitlements and only fall back on checking their pledge history if they aren't currently pledged to the tier you're looking for.

For any questions, help, suggestions or feature requests, please feel free to contact me at nbpsup@gmail.com