Pinax Referrals

About Pinax

Pinax is an open-source platform built on the Django Web Framework. It is an ecosystem of reusable Django apps, themes, and starter project templates. This collection can be found at http://pinaxproject.com.

Important Links

Where you can find what you need:

Releases: published to PyPI or tagged in app repos in the Pinax GitHub organization
Global documentation: Pinax documentation website
App specific documentation: app repos in the Pinax GitHub organization
Support information: SUPPORT.md file in the Pinax default community health file repo
Contributing information: CONTRIBUTING.md file in the Pinax default community health file repo
Current and historical release docs: Pinax Wiki

pinax-referrals

Overview

pinax-referrals provides a site with the ability for users to publish referral links to specific pages or objects and then record any responses to those links for subsequent use by the site.

For example, on an object detail page, the site builder would use a template tag from pinax-referrals to display a referral link that the user of the site can send out in a Tweet. Upon clicking that link, a response to that referral code will be recorded as well as any other activity that the site builder wants to track for that session.

It is also possible for anonymous referral links/codes to be generated which is useful in marketing promotions and the like.

Supported Django and Python Versions

Django / Python	3.10	3.11	3.12	3.13	3.14
3.2	*
4.2	*	*	*
5.2	*	*	*	*	*
6.0			*	*	*
6.1			*	*	*

Documentation

Installation

To install pinax-referrals:

    $ pip install pinax-referrals

Add pinax.referrals to your INSTALLED_APPS setting:

INSTALLED_APPS = [
    # other apps
    "pinax.referrals",
]

See the list of settings to modify pinax-referrals's default behavior and make adjustments for your website.

Add pinax.referrals.middleware.SessionJumpingMiddleware in order to link up a user who registers and authenticate after hitting the initial referral link. Make sure that it comes after the django.contrib.auth.middleware.AuthenticationMiddleware:

MIDDLEWARE = [
    # other middleware
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "pinax.referrals.middleware.SessionJumpingMiddleware",
]

Lastly add pinax.referrals.urls to your urls definition:

urlpatterns = [
    # other urls
    url(r"^referrals/", include("pinax.referrals.urls", namespace="pinax_referrals")),
]

Usage

`Referral.create`

This is the factory method that the create_referral view calls but it can be called directly in case you needed to integrate with pinax-referrals in a different way.

For example, you might want to automatically give every user a referral code that is emailed to them upon signup. In this case, you could created a one-to-one relationship between their Profile and pinax-referrals' Referral and create a signal receiver for when the Profile is created that calls:

referral = Referral.create(
    user=profile.user,
    redirect_to=reverse("home")
)
profile.referral = referral
profile.save()

Then you could, in the welcome email that you send them upon signup, render their referral url that they could forward on to other users:

    {{ user.get_profile.referral.url }}

The only required parameter for Referral.create is redirect_to. It must be a URL on your own site (a path such as /signup/, or an absolute URL on the host serving the referral link or on a host listed in PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS): the create_referral view rejects any other value with a 400 response, and process_referral redirects to / instead of following a stored redirect_to that points elsewhere. If you don't specify a user it will be recorded as None. This can be useful if you want to attach a relationship between some object in your system to a referral that might not have a user associated with it.

You can also pass in an optional label kwarg to Referral.create if you want to allow your users to create and manage multiple referrals as labeling them becomes important in order to keep track of them.

At runtime, you can append the redirect_to URL parameter to your referral URL to dynamically redirect to an alternate destination.

{{ user.get_profile.referral.url }}?redirect_to=/special/

The URL parameter used can be altered in your settings file.

Expiring referrals

A referral stops counting once its expired_at time has passed. Following the link still redirects to its redirect_to, so links already shared do not break, but no response is recorded and no referral cookie is set. Referral.record_response records nothing more for it, and SessionJumpingMiddleware no longer links its earlier responses to a user who logs in. A referral whose expired_at is None (the default) never expires. Referral.is_active() tells you whether a referral still counts.

referral.expired_at = timezone.now() + timedelta(days=30)
referral.save()

`Referral.record_response`

The classmethod record_response will attempt to see if the current user or session has any previous responses to an initial referral and, if so, will then proceed to record the response action.

For example, say you want to record the fact that the user did some site activity after clicking on the referral link you tweeted and subsequently decided to register and login to the site:

from pinax.referrals.models import Referral


def my_view(request, **kwargs):
    # other code
    referral_response = Referral.record_response(request, "SOME_ACTION")

In this case the referral_response will be None if the user on the request doesn't have any previously recorded referral responses. In addition, if the user has responded to more than one Referral code, then this will associate the activity with the most recent response.

In addition, this supports passing an options target keyward argument, if you wanted to record associations with specific objects. For example:

Referral.record_response(request, "SOME_ACTION", target=some_object)

This will record a generic foreign key to some_object that you can use elsewhere to identify activity from your referral at a deeper level than just based on the action label.

`Referral.referral_for_request`

This class method will give you a referral object for the given request in case you need to apply any business logic in your project. For example, to do any comparisons on the referral.target with another object you have in context for segmenting permissions or authorizations to make your referral system more fine grained.

Settings

`PINAX_COOKIE_MAX_AGE`

Defaults to None

The total amount of time (in seconds) the cookie lasts in the client's browser.

The pinax-referral cookie holds the visitor's session key. It is set HttpOnly and SameSite=Lax, and Secure when the referral link was followed over HTTPS.

`PINAX_REFERRALS_IP_ADDRESS_META_FIELD`

Defaults to "HTTP_X_FORWARDED_FOR"

This is the header value that is retrieved from request.META to record the ip address of the the respondent.

`PINAX_REFERRALS_GET_CLIENT_IP_CALLBACK`

Defaults to "pinax.referrals.callbacks.get_client_ip"

If the default IP determining function doesn't suit you, supply a path with your own function (takes a request as a parameter).

`PINAX_REFERRALS_SECURE_URLS`

Defaults to False

Setting this to True will produce urls with https instead of http.

`PINAX_REFERRALS_CODE_GENERATOR_CALLBACK`

Defaults to "pinax.referrals.callbacks.generate_code"

Externalizes the logic that generates the referral code. pinax-referrals ships with a default that will generate a random 40-character alpha-numeric string that can also be used as a reference implementation. The callable defined by the fully qualified path is passed the class of the referral model (or Referral) and the actual referral model instance. This means that you can easily customize the code for each user.

For example:

def generate_code(referral_class, referral):
    return referral.user.username

Since only one Referral with the same code can exist at the same time the value returned by generate_code needs to be unique.

`PINAX_REFERRALS_ACTION_DISPLAY`

Defaults to {"RESPONDED": "Clicked on referral link"}

Defines a dictionary mapping action codes for responses to user-friendly display text. Used by the action_display template filter.

`PINAX_REFERRALS_REDIRECT_ATTRIBUTE`

Defaults to redirect_to

Defines the URL attribute to retrieve dynamic referral redirection URLs from.

The URL is checked by django.utils.http.url_has_allowed_host_and_scheme, so if it points to a host other than the one serving the request (or one listed in PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS), the view will redirect to Referral.redirect_to instead.

`PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS`

Defaults to []

Hosts that referral links may redirect to in addition to the host serving the request, for sites that serve referral links on one domain and land visitors on another (for example links on www.example.com that open app.example.com). Entries are matched like Django's ALLOWED_HOSTS: "www.example.com" matches that host only, and ".example.com" matches example.com and all of its subdomains. A port in the target URL is ignored. Unlike ALLOWED_HOSTS, "*" matches nothing, because allowing every host would turn referral links back into an open redirect.

PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS = ["app.example.com", ".example.org"]

The list applies to redirect_to when create_referral stores it, to the stored redirect_to when a link is followed, and to the redirect_to URL parameter. On a request served over HTTPS, an absolute target must use https.

Signals

user_linked_to_response is a signal that provides the single argument of a response object that has just been linked to a user. You can use this to provide further automatic processing within your site, such as adding permissions, etc. to users that signup as a result of a referral.

For example:

@receiver(user_linked_to_response)
def handle_user_linked_to_response(sender, response, **kwargs):
    if response.action == "SOME_SPECIAL_ACTION":
        pass  # do something with response.user and response.referral.target (object that referral was linked to)

Templates

pinax-referrals comes with a single template fragment for rendering a simple form that is used in creating a referral link.

`_create_referral_form.html`

This is a snippet that renders the form that upon submission will create the referral link. By default it is rendered with the class referral with the following context variables:

{
    "url": url,
    "obj": obj,
    "obj_ct": ContentType.objects.get_for_model(obj)
}

or if no object was passed into the create_referral template tag then the context would simply blank for obj and obj_ct.

Template Tags and Filters

`create_referral`

In order to use pinax-referrals in your project you will use the create_referral template tag wherever you'd like a user to be able to get a referral link to a page or a particular object:

{% load pinax_referrals_tags %}

{% create_referral object.get_absolute_url object %}

The use of object in this case is optional if you just want to record referrals to a particular url. In that case you can just do:

{% load pinax_referrals_tags %}

{% url my_named_url as myurl %}

{% create_referral myurl %}

This will render a form that is defined in pinax/referrals/_create_referral_form.html which will POST to a view and return JSON. The intent of this form is that it be used with an AJAX submission and handler.

The recommended way is to use jquery.form and to do the following:

$(function () {
    $('form.referral').each(function(i, e) {
        var form = $(e);
        options = {
            dataType: "json",
            success: function(data) {
                form.html('<input type="text" value="' + data.url + '" />');
                form.find("input[type=text]").select();
            }
        }
        form.ajaxForm(options);
    });
});

`referral_responses`

This template tag is an assignment tag that, given a user, sets a context variable with a queryset of all responses for all referrals owned by the user, in order of when they were created.

The use case for this is displaying all the activities associated with the user's different labeled referrals.

Example:

{% load pinax_referrals_tags %}
{% referral_responses user as responses %}

{% for response in responses %}
    {# response is a ReferralResponse object #}
{% endfor %}

`action_display`

This filter converts a response code into a user friendly display of what that code means. The definitions exist in the setting PINAX_REFERRALS_ACTION_DISPLAY.

{% load pinax_referrals_tags %}

<p>
    {{ response.action|action_display }}
</p>

Development

Migrations

If you need to make migrations for pinax-referrals, run:

    $ python manage.py makemigrations referrals

You may need to do this if you use a custom user model and upgrade Django.

Change Log

4.5.0 (2026-10-16)

Security: fixed an open redirect. Any logged-in user could POST an external redirect_to to the create_referral view and get a referral link on your domain that bounced visitors to that external site. create_referral now rejects a redirect_to that is not on the requesting host (400), and process_referral no longer follows a stored off-site redirect_to; it redirects to / instead. Behaviour change: existing referrals whose redirect_to points to another host, including ones created directly with Referral.create, now land on / instead of that host.
Added the PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS setting. Sites whose referral links redirect to another of their own hosts or subdomains (for example from www to app) list those hosts there; without it, the fix above sends those visitors to /.
Referral.expired_at is now enforced (#7). An expired referral link still redirects, but records no response and sets no referral cookie; Referral.record_response records nothing for it; and SessionJumpingMiddleware no longer links its responses to a user who logs in. Added Referral.is_active(), and expired_at to the admin list and filters. Behaviour change: referrals that already have an expired_at in the past stop counting.
Dropped support for Python 3.8 and 3.9, which are past end of life; python_requires is now >=3.10. Django 3.2 is now tested on Python 3.10 only, and Django 4.2 on Python 3.10-3.12.
Now tested against Django 3.2, 4.2, 5.2, 6.0, 6.1 and main, on Python 3.10-3.14
The pinax-referral cookie, which holds the visitor's session key, is now HttpOnly and SameSite=Lax, and Secure when set over HTTPS. Behaviour change: JavaScript can no longer read it.
Fixed a server error (500) in process_referral when the redirect_to URL parameter or a stored redirect_to is a bare word that is not a URL name (e.g. ?redirect_to=foo). It now falls back to the next target, as for an off-site URL.
Fixed a 500 on every request of a logged-in user whose pinax-referral cookie has no :, in SessionJumpingMiddleware (and in Referral.for_request). The cookie is dropped instead.
create_referral returns 400 instead of a 500 when obj_ct_pk and obj_pk do not identify an existing object.
Referral.referral_for_request, and so Referral.record_response, now fetches only the visitor's latest response instead of all of them.

4.4.0 (2026-07-28)

Dropped support for Django < 3.2 and Python < 3.8
Now tested against Django 3.2, 4.2, 5.2, 6.0 and main, on Python 3.8-3.13
Added python_requires so pip no longer installs the package on unsupported Python versions
Removed compatibility shims that the new baseline makes dead code (default_app_config, the MiddlewareMixin fallback, the is_safe_url fallback, and the pkg_resources fallback)
Removed the distutils dependency from the test runner
Updated the linting toolchain (flake8 7, isort 5)

4.3.0 (2023-06-07)

added tolerance to the ending slash in URL
ReferralResponse now stores http_referrer
Updated testing. Tests now passes in Django 2.2-5.1 and Python 3.7-3.12

4.2.0 (2023-01-12)

Added referral model instance parameter to generate_code callback (PINAX_REFERRALS_CODE_GENERATOR_CALLBACK variable)

4.1.0 (2022-12-12)

Update to support Django 2.2-4.1, Python 3.7-3.10
Fixed admin views performance
Fixed AttributeError when referral_responses_for_request() was called with WSGIRequest
Added customizable callback for get_client_ip through PINAX_REFERRALS_GET_CLIENT_IP_CALLBACK variable
Fixed potential phishing attack risk in redirect_to parameter. Now the parameter is checked with django.utils.http.url_has_allowed_host_and_scheme to prevent redirection to unsafe domain.

4.0.2

Added setting to set the cookie's max age in client's browser

4.0.1

Changes to admin.py and models.py to increase overridability

4.0.0

Drop Django 1.11, 2.0, and 2.1, and Python 2,7, 3.4, and 3.5 support
Add Django 2.2 and 3.0, and Python 3.6, 3.7, and 3.8 support
Update packaging configs
Direct users to community resources

3.0.5

Simple fix for #46. Increase the length of the ip_address, so IPv6 address array from HTTP_X_FORWARDED_FOR can be stored.

3.0.4

Fixing search in referral admin against "user"

3.0.3

Changes to setup.py

3.0.2

Use Django 2.0 reverse import

3.0.1

Change is_authenticated to property in models.py

3.0.0

Add Django 2.0 compatibility testing
Drop Django 1.9 and Python 3.3 support
Convert CI and coverage to CircleCi and CodeCov
Add PyPi-compatible long description
Add URL namespacing
Standardize documentation layout
Drop Django v1.8, v1.10 support
Update installation requirements for django>=1.11
Remove unused doc build support

2.0.0

Renamed from anafero to pinax-referrals
Brought up to date with latest Pinax app standards

1.0.1

Fix deprecation warning in urls

1.0

ENHANCEMENT: made GFK fields on Referral blankable

0.10.0

ENHANCEMENT: added a signal to provide notifications of when a referred user authenticates

0.9.1

BUG: Fix issue where target response is None

0.9

FEATURE: added ability to record a specific object in reference to each response

Migration from 0.8.1

ALTER TABLE "anafero_referralresponse"
 ADD COLUMN "target_content_type_id" integer REFERENCES "django_content_type" ("id") DEFERRABLE INITIALLY DEFERRED,
 ADD COLUMN "target_object_id" integer;

0.8.1

ENHANCEMENT: switched over to use django.utils.timezone.now instead of datetime.datetime.now

0.8

FEATURE: added ability to override filtering of responses

0.7

ENHANCEMENT: Made admin a bit more usable

0.6.1

ENHANCEMENT: Rewrote referral_responses to run on Django 1.3

0.6

ENHANCEMENT: send full context to the create_referral template tag

0.5.2

BUG: Fixed a stupid mistake

0.5.1

BUG: fixed an issue with sessions in Django 1.4

0.5

FEATURE: added ability to label referrals
ENHANCEMENT: added support for bootstrap-ajax.js
FEATURE: added a referral_responses assignment template tag
FEATURE: added an activity_display template filter
ENHANCEMENT: added a new classmethod on Referral for getting a referral object for a given request object.

Migration from 0.4

ALTER TABLE "anafero_referral" ADD COLUMN "label" varchar(100) NOT NULL DEFAULT '';

0.4

FEATURE: Add ability to define code generators external to anafero
ENHANCEMENT: Add ability to pass in a user to referral.respond in cases when request.user isn't set yet (e.g. during signup)
FEATURE: Add ability to get a referral object from a request

0.3

FEATURE: changed user on Referral to be nullable, thus enabling anonymous or site administered referral codes

0.2.1

BUG: fixed target not being set in the create_referral ajax view

0.2

DOC: fixed a typo in the docs
ENHANCEMENT: added a response count property
ENHANCEMENT: added the return of the referral code along with the URL in the ajax reponse of create_referral
BUG: added the return of the proper mimetype in the create_referral ajax view
ENHANCEMENT: moved the building of the URL for the referral code to a property on the Referral model
FEATURE: added the ability to control referral code generation properties via settings at the site level
BUG: fixed the url generation to include https if the site is configured to run SSL
BUG: only delete cookies if user is present
BUG: make sure to set a session value to prevent session key from changing with each request

0.1

initial release

History

This project was originally named anafero and was created by the team at Eldarion. It was later donated to Pinax and at that time renamed to pinax-referrals.

Contribute

Contributing information can be found in the Pinax community health file repo.

Code of Conduct

In order to foster a kind, inclusive, and harassment-free community, the Pinax Project has a Code of Conduct. We ask you to treat everyone as a smart human programmer that shares an interest in Python, Django, and Pinax with you.

Connect with Pinax

For updates and news regarding the Pinax Project, please follow us on Twitter @pinaxproject and check out our Pinax Project blog.

Name		Name	Last commit message	Last commit date
.circleci		.circleci
.github		.github
pinax		pinax
.gitignore		.gitignore
AUTHORS		AUTHORS
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
makemigrations.py		makemigrations.py
manage.py		manage.py
requirements_test.txt		requirements_test.txt
runtests.py		runtests.py
settings.py		settings.py
setup.py		setup.py
tox.ini		tox.ini

Latest commit

History

Folders and files

Repository files navigation

Pinax Referrals

Table of Contents

About Pinax

Important Links

pinax-referrals

Overview

Supported Django and Python Versions

Documentation

Installation

Usage

Referral.create

Expiring referrals

Referral.record_response

Referral.referral_for_request

Settings

PINAX_COOKIE_MAX_AGE

PINAX_REFERRALS_IP_ADDRESS_META_FIELD

PINAX_REFERRALS_GET_CLIENT_IP_CALLBACK

PINAX_REFERRALS_SECURE_URLS

PINAX_REFERRALS_CODE_GENERATOR_CALLBACK

PINAX_REFERRALS_ACTION_DISPLAY

PINAX_REFERRALS_REDIRECT_ATTRIBUTE

PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS

Signals

Templates

_create_referral_form.html

Template Tags and Filters

create_referral

referral_responses

action_display

Development

Migrations

Change Log

4.5.0 (2026-10-16)

4.4.0 (2026-07-28)

4.3.0 (2023-06-07)

4.2.0 (2023-01-12)

4.1.0 (2022-12-12)

4.0.2

4.0.1

4.0.0

3.0.5

3.0.4

3.0.3

3.0.2

3.0.1

3.0.0

2.0.0

1.0.1

1.0

0.10.0

0.9.1

0.9

Migration from 0.8.1

0.8.1

0.8

0.7

0.6.1

0.6

0.5.2

0.5.1

0.5

Migration from 0.4

0.4

0.3

0.2.1

0.2

0.1

History

Contribute

Code of Conduct

Connect with Pinax

License

About

Resources

Code of conduct

`Referral.create`

`Referral.record_response`

`Referral.referral_for_request`

`PINAX_COOKIE_MAX_AGE`

`PINAX_REFERRALS_IP_ADDRESS_META_FIELD`

`PINAX_REFERRALS_GET_CLIENT_IP_CALLBACK`

`PINAX_REFERRALS_SECURE_URLS`

`PINAX_REFERRALS_CODE_GENERATOR_CALLBACK`

`PINAX_REFERRALS_ACTION_DISPLAY`

`PINAX_REFERRALS_REDIRECT_ATTRIBUTE`

`PINAX_REFERRALS_ALLOWED_REDIRECT_HOSTS`

`_create_referral_form.html`

`create_referral`

`referral_responses`

`action_display`