Installation and Setup¶
Install django-flexible-subscriptions and its dependencies¶
django-flexible-subscriptions (which will install Django
as a dependency). It is strongly recommended you use a virtual
environment for your projects. For example, you can do this easily
$ pipenv install django-flexible-subscriptions
Add django-flexible-subscriptions to your project¶
django-flexible-subscriptionsto your settings file. While not mandatory, it is very likely you will also want to include the
django.contrib.adminapps as well (see Understanding a Description Plan for details).
INSTALLED_APPS = [ # Django applications 'django.contrib.auth', 'django.contrib.admin', ... # Your third party applications 'subscriptions', ... ]
- Run the package migrations:
$ pipenv run python manage.py migrate
- Add the
django-flexible-subscriptionsURLs to your project:
import subscriptions from django.contrib import admin # Optional, but recommended from django.urls import include, urls urlpatterns = [ ... path('subscriptions/', include('subscriptions.urls')), path('admin/', include(admin.site.urls), # Optional, but recommended ... ]
- You can test that the project is properly setup by running the
pipenv run python manage.py runserver) and visiting
While not required, you are able to customize aspects of Django Flexible Subscriptions in your settings file. At a minimum, you will probably want to set the following settings:
# Set your currency type DFS_CURRENCY_LOCALE = 'en_us' # Specify your base template file DFS_BASE_TEMPLATE = 'base.html'
A full list of settings and their effects can be found in the settings documentation.
Understanding a Subscription Plan¶
Django Flexible Subscriptions uses a
Plan model to describe a
subscription plan. A
Plan describes both billing details and
user permissions granted.
User permissions are dictacted by the Django
Group model, which is
included as part of the authentication system. Django Flexible
Subscriptions will add or remove a
Group from a
User based on
the status of the user subscription. You may specify the permissions
User is granted by associating them to that Group and running any
permission checks as needed. See the Django documenation on “User
authentication in Django” for more details. If you do not need to
grant a user permissions with a subscription, you may ignore the
Plan contains the following details to dictate
how it functions:
- Plan name: The name of the subscription plan. This will be displayed to the end user in various views.
- Plan description: An optional internal description to help describe or differentiate the plan for the developer. The end user does not see this.
- Group: The
Groupmodel(s) associated to this plan.
- Tag: Custom tags associated with this plan. Can be used to organize or categorize related plans.
- Grade period: The number of days a subscription will remain active for a user after a plan ends (e.g. due to non-payment).
- Plan cost: Describes the pricing details of the plan.
One or more
PlanCost models may be associated to a
allows you to offer the same plan at difference prices depending on
how often the billing occurs. This would commonly be used to offer a
discounted price when the user subscribes for a longer period of time
(e.g. annually instead of monthly). A
PlanCost will contain the
- Recurrence period: How often the plan is billed per recurrence unit.
- Recurrence unit: The unit of measurement for the recurrence
- Cost: The amount to charge at each recurrence period.
Setup a Subscription Plan¶
Once Django Flexible Subscriptions is setup and running, you will be able to add your first subscription.
You will need an account with staff/admin access to proceed with
the following steps. All referenced URLs assume you have added
django-flexible-subscriptions URLs at
/subscriptions/dfs/to access the Developer Dashboard.
2. Click the Subscription plans link or visit
/subscriptions/dfs/plans/. Click on the Create new plan button.
- Fill in the plan details and click the Save button.
Understanding a Subscription Plan List¶
Django Flexible Subscriptions provides basic support to add a
“Subscribe” page to your site to allow users to select a subscription
plan. The plans listed on this page are controlled by the
PlanList model includes the following details:
- Title: A title to display on the page (may include HTML content).
- Subttile: A subtitle to display on the page (may include HTML content).
- Header: Content to display before the subscription plans are listed (may include HTML content).
- Header: Content to display after the subscription plans are listed (may include HTML content).
- Active: Whether this list is active or not.
The first active
PlanList instance is used to populate the
subscribe page. You will need to inactivate or delete older
PlanList instances if you want a newer one to be used.
PlanList is created, you will be able to associate
instances to specify the following details:
- HTML content: How you want the plan details to be presented (may include HTML content).
- Subscribe button text: The text to display on the “Subscribe” button at the end of the plan description.
Creating a Plan List¶
Once you have created you subscription plan, you can create your
/subscriptions/dfs/to access the Developer Dashboard.
- Click the Plan lists button or visit
/subscriptions/dfs/plan-lists/. Click on the Create a new plan list button.
- Fill in the plan list details and click the Save button.
- To add
Planinstances to your
PlanListclick the Manage plans button on the Plan Lists page.
- Click on the Add plan button, fill in the desired details and click the Save buton.
- You can now visit
/subscriptions/subscribe/to see your plan list.
If you completed all the steps above, you should now have a working subscription system on your development server. You will likely want to add payment handling and a task runner to automate subscription renewals and expiries. Instructions and examples for this can be found the Advanced usage section.
Considerations for Production¶
When moving Django Flexible Subscriptions to a production environment, you will probably want to consider the following:
django-flexible-subscriptionscomes with its own
styles.cssfile - you will need to ensure you run the
collectstaticmanagement command if you have not overriden it with your own file.
django-flexible-subscriptionsis intended to be extended to implement payment processing. The base view will automatically approve all payment requests and should be overriden if this is not the desired behaviour.
django-flexible-subscriptionsincludes management commands to assist with managing subscription renewals and expiries. While these can be ran manually, you should consider implementing some task manager, such as
celery, to run these commands on a regular basis.