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 `billing` to your list of installed apps
4. run ``python manage.py 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 settings.py
The example project, for instance, has this declaration in it's settings.py::
BILLING_PROCESSORS = {
'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 `products.py` file
An example of defining products can be seen in
example_saas_project/core/products.py
Since products are often created by class hierarchies, only those products
which you wish to be subscribable should be imported into a billing.py
Point to this billing definitions module with ``BILLING_DEFINITIONS``
in settings.py. In the example, the billing definitions are
in example_saas_project/core/billing.py, so in settings.py, we've added::
BILLING_DEFINITIONS = 'example_saas_project.core.billing'
4. Templates
------------
You need to define a number of templates. There are examples in
example_saas_project/core/templates/billing
billing/current_subscription.html
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
billing/details.html
^^^^^^^^^^^^^^^^^^^^
TODO
billing/history.html
^^^^^^^^^^^^^^^^^^^^
TODO
billing/overview.html
^^^^^^^^^^^^^^^^^^^^^
TODO
billing/subscription_billing_details.html
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
billing/subscription_confirmation.html
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
Motivation
==========
TODO
Billing Processors
==================
A billing processor is a class that provides a one method and one attribute
has_valid_billing_details(account)
Returns whether the given billing account has valid billing details
registered with the processor.
billing_details_creation_form
A Django form which collects the details needed to bill an account. This form
should have a `save()` method which saves the billing details. This method
may assume that the account for which details are being submitted is stored
in the `billing_account` property.
Additionally, any urls in the processor's urls.py 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
---------------------------
TODO
Processor Routers
=================
A billing processor router is a class that provides a single method:
get_processor_for_account(account)
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 BILLING_PROCESSOR_ROUTERS
setting. This setting defines a list of class names, each specifying a
router that should be used by the master router (`billing.processor.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 `default` router.
This architecture/API is very much inspired by Django's database routers
Management Commands
===================
django-billing provides the 'subscribe_user_to_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).