Flattr Developer Platform

Partner site integration

This documentation is for Flattr Partners.

You can apply for partnership over at our partnership site.

Revenue Sharing

To take part in revenue sharing with Flattr you need to generate a Revenue Sharing Key on our partner site. This key is unique and used to identify all the flattrs you make as a partner on Flattr.

Revenue Sharing with Embedded button/Auto-submit

If you use javascript buttons in your Flattr integration you need to add your revshare key ( available on the partner site to either the Flattr javascript or to a attribute on the Flattr button.

Example: Add revenue sharing key to the Flattr Javascript

<script type="text/javascript">
/* <![CDATA[ */
(function() {
    var s = document.createElement('script');
    var t = document.getElementsByTagName('script')[0];

    s.type = 'text/javascript';
    s.async = true;
    s.src = '//api.flattr.com/js/0.6/load.js'+
        '?mode=auto&revsharekey=YOUR_REVENUE_SHARING_KEY';

    t.parentNode.insertBefore(s, t);
 })();
/* ]]> */
</script>

Example: Add the revenue sharing key as a data-flattr attribute on the link HTML tag

<a class="FlattrButton" style="display:none;"
    title="This is my title"
    data-flattr-uid="flattr"
    data-flattr-tags="text, opensource"
    data-flattr-category="text"
    data-flattr-revsharekey="YOUR_REVENUE_SHARING_KEY"
    href="http://wp.local/?p=444">

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Lorem ipsum dolor sit amet, consectetur adipiscing
    Maecenas aliquet aliquam leo quis fringilla.
</a>

REST API

If you are flattering through our REST API you need to make certain that your Revenue Sharing Key is connected to your Application on the partner site. If it is, you won't need to do anything futher.

Partner namespaces

Introduction

Partner namespaces is a way for partners to create Things for their users' content without the user having to preregister at Flattr. When the user later on signs up for Flattr they will receive all the pending flattrs and gain ownership of all of their Things.

The mechanism uses non-flattr user identifiers to identify ownership of the things and lets the user claim it's things and flattrs by later confirming that its the rightful owner of that identifier.

Namespaces are created in dialog with Flattr, so contact us and we can discuss futher.

Web Hook Callbacks are supported for notifying partners when something happens to one of their users unclaimed things - such as them receiving flattrs. That way partners can easily communicate what is happening on Flattr to their users and make them aware that they have flattrs to claim..

Auto-submit / Embedded buttons

The first step is to add a way for users to be able to flattr the content on your site.

The best user experience is achieved by using our javascript based embedded buttons which embeds buttons as iframes through which logged in users can flattr right away.

If for any reason embedded buttons won't work one can instead use our static auto-submit to open a page on Flattr.com with the thing on which it can be flattred.

Through the auto-submit process (auto-submitting means that a Flattr thing is created automatically when the first flattr is made - they don't have to be presubmitted) the description of the thing is currently also added - the name, category, language etc.

However - we're looking at moving away from auto-submit provided description data in the future and fetch the description of the thing from its URL instead - using Open Graph data or similar. Partners need to keep this in mind when choosing URL:s for their things. Feedback is also welcome.

Embedded Buttons

Embedded buttons for partners work the same way as a normal Flattr button.

The difference between normal buttons and the ones used by partners is that a partner may assign an owner parameter instead of the uid parameter used by ordinary buttons. The owner parameter contains an identifier for a non-flattr user. See a list of supported identifiers in the section Supported user identifiers at the end of this document.

Static Auto-submit

The static auto-submit is a link that redirects to either an existing thing or to a temporary page where the thing can be flattred and thus also created through the auto-submit.

The basic URL for the static auto-submit is https://flattr.com/submit/auto and to that a couple of query parameters are added see embedded button documentation. As with the Embedded buttons, a partner may assign an owner instead of the uid parameter.

Example Auto-submit URL

https://flattr.com/submit/auto?url=http://example.com/&owner=twitter:user:id:123&title=Example

Web Hook callbacks

For partners to get notified when something happens to their site's unclaimed things we have added support for web hooks - this means that partners can pass the notification on to the owner of thing so that partners can be sure that the user knows about it.

A single web hook URL is registered with us and which events that should be sent to it. Whenever an event occurs we do a POST-request to that URL with a form encoded body containing event specific parameters as well as a _event parameter indicating the type of event. Partner sites should always check the _event parameter prior to processing an event to be sure that they are processing the right event.

Available Web Hook Events

Unclaimed thing receives a pending flattr

Event name: pendingclickcreate

Parameters:

Supported user identifiers

If you think a identifier is missing don't hesitate contacting us about it.

Verifying custom identifiers

If we have arranged it so that you can verify that a given Flattr account is owned by a user on your system, you can use a API call to associate the two accounts. This will make all pending things associated with the user on your system to automatically be claimed by the Flattr account.

Parameters
Request
POST https://api.flattr.com/rest/v2/users/:username/verify
Verify an authenticated user
POST https://api.flattr.com/rest/v2/user/verify
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
Errors
Visit Flattr.com to learn more about Flattr.