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).