Need help with django-billing?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

145 Stars 33 Forks GNU Affero General Public License v3.0 45 Commits 4 Opened issues


A simple, generic plans-, pricing- and recurring-billing app.

Services available


Need anything else?

Contributors list

# 37,041
41 commits
# 536,050
1 commit
# 425,862
1 commit

django-billing is a simple, generic, plans, pricing and recurring billing app. It enforces quotas and tracks pre-paid and usage-based features.

Quick Start

There are four steps needed to get started:

  1. Install django-billing
  2. Plug in a billing processor
  3. Define your products
  4. Create your templates

1. Installation

  1. pip install django-billing
  2. set up the dependencies
  3. add
    to your list of installed apps
  4. run

    python migrate billing

2. Billing Processors

While django-billing collects all the information needed to bill customers, it doesn't take a stance on how payments should be collected. django-billing delegates responsibility for actually charging a customer to a billing processor. Individual billing processors interface with different payment collection gateways to actually collect money.

Usually you will just need to install a billing processor by adding it into the BILLING_PROCESSORS dict in your

The example project, for instance, has this declaration in it's

    'default': 'billing.processor.simple_account.processor.SimpleAccountBillingProcessor',

For more details see the section on billing processors below.

3. Defining Products

Products are what your customers subscribe to, and are defined as classes (in a similar manner to Django models).

A Product class is used for three puposes:

  1. to check the usage of a given feature
  2. to enforce limits upon the usage of features
  3. to calculate information for invoices

For example, in the example project shipped with django-billing, there is a base definition

They are defined as a collection of features (each of which is composed of a value and a provisioning scheme) along with certain details about usage limits and pricing.

django-billing relies on python-pricing to set up the pricing model.

products should be defined in a

An example of defining products can be seen in examplesaasproject/core/

Since products are often created by class hierarchies, only those products which you wish to be subscribable should be imported into a

Point to this billing definitions module with

in In the example, the billing definitions are in examplesaasproject/core/, so in, we've added::
BILLING_DEFINITIONS = 'example_saas_project.core.billing'

4. Templates

You need to define a number of templates. There are examples in examplesaasproject/core/templates/billing

billing/current_subscription.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


billing/details.html ^^^^^^^^^^^^^^^^^^^^


billing/history.html ^^^^^^^^^^^^^^^^^^^^


billing/overview.html ^^^^^^^^^^^^^^^^^^^^^


billing/subscriptionbillingdetails.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


billing/subscription_confirmation.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



A few years ago, I had a side project that I was ready to launch as a small business. All I needed to do was figure out how to charge for it. Turns out billing systems are hard to build.

But pretty much every company needs one, so a number of SaaS companies have sprung up recently to help handle recurring payments. Unfortunately they only deal with actually issuing a charge. Tracking usage, and determining whether a user has permission to perform an action in the app (possibly based on their usage-to-date or their plan level) is still left up to the app developer.

Because this information is so tightly linked with the app itself, it does make sense to keep this functionality within the app rather than in a third-party service, but it doesn't make sense for everyone to reimplement it themselves.

Ideally, by making it easier to implement a pricing model, django-billing can help smaller projects close the time gap between first creating value for users and actually capturing some of that value for themselves.

Billing Processors

A billing processor is a class that provides a one method and one attribute


Returns whether the given billing account has valid billing details registered with the processor.


A Django form which collects the details needed to bill an account. This form should have a

method which saves the billing details. This method may assume that the account for which details are being submitted is stored in the

Additionally, any urls in the processor's will be mapped into the billing url space at '/billing/processors/{{ processor_name }}/...'

This can be useful for webhooks callbacks from payment processesor systems.

Writing a Billing Processor


Processor Routers

A billing processor router is a class that provides a single method:


Suggests the billing processor that should be used for the given account.

Returns None if there is no suggestion

Using Routers

Billing processor routers are installed using the BILLINGPROCESSORROUTERS setting. This setting defines a list of class names, each specifying a router that should be used by the master router (


The master router is used by django-billing to decide which processor to use. Whenever an operation needs to perform an operation using a processor, it consults the master router, which tries each registered router, in turn, until a processor suggestion is found. If no suggestion is found, the master router yields the


This architecture/API is very much inspired by Django's database routers

Management Commands

django-billing provides the 'subscribeuserto_product' management command to manually subscribe a user. This is especially useful when providing products which require manual pre-approval (i.e. products to which the user should not be able to subscribe themselves).

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.