https://github.com/calvinchengx/django-subscription

Subscriptions or Recurring Billing App for django
https://github.com/calvinchengx/django-subscription

Last synced: 11 days ago
JSON representation

Subscriptions or Recurring Billing App for django

• Host: GitHub
• URL: https://github.com/calvinchengx/django-subscription
• Owner: calvinchengx
• License: other
• Fork: true (zhaque/django-subscription)
• Created: 2013-01-15T03:45:49.000Z (about 12 years ago)
• Default Branch: master
• Last Pushed: 2014-04-26T17:06:26.000Z (almost 11 years ago)
• Last Synced: 2024-10-02T09:15:17.391Z (4 months ago)
• Language: Python
• Homepage: http://saaskit.org
• Size: 228 KB
• Stars: 2
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README

Awesome Lists containing this project

README

        
Django Subscription

===================

Django-subscription is an application for handling PayPal-based pay

subscriptions. Module does not handle explicit permissions; instead,

subscribed user are automatically added to predefined groups using

`django.contrib.auth' application. It needs django-paypal application

available at [http://github.com/johnboxall/django-paypal/] for handling

payments.

Table of Contents

=================

1 Installation

2 Settings

3 Models

    3.1 Subscription

        3.1.1 methods

    3.2 UserSubscription

        3.2.1 methods

    3.3 Transaction

4 Signals

5 Views

6 URLs

7 Templates

8 Subscription change

9 Example code

10 Bugs and omissions

    10.1 Plans

11 License

1 Installation

~~~~~~~~~~~~~~

  Copy or symlink `subscription/' directory on Python path (`setup.py'

  script for automated installation will be supplied later on). Module

  contents are available in the `subscription' module.

  In order to use application, add `subscription' to INSTALLED_APPS in

  Django project `settings.py' file.

2 Settings

~~~~~~~~~~

  In project's `settings.py' file `SUBSCRIPTION_PAYPAL_SETTINGS'

  should be set to a dictionary with default PayPal button settings,

  as described in django-paypal documentation. At least the `business'

  key should be set to your PayPal business e-mail.

  `SUBSCRIPTION_PAYPAL_FORM' can be set to a form class pathname as

  string to use custom PayPal payment button class.  Default is

  'paypal.standard.forms.PayPalPaymentsForm'.  To use PayPal encrypted

  buttons or shared secrets, specify needed django-paypal settings and

  set an appropriate class here.

  `SUBSCRIPTION_GRACE_PERIOD' is an integer and it specifies number of

  days after individual subscription expiry on which account is

  actually treated as expired.  Default is 2 days.  Intent of this

  setting is that recurring payments take place e.g. monthly, so

  either on last day of subscription period, or even on first day

  after it; this way we avoind unintentionally locking out user

  account.

3 Models

~~~~~~~~

  Two models defined by the application are available in the

  `subscription.models' module.

3.1 Subscription

================

   Main model used by the application is `Subscription'.  It

   represents a single subscription available for users.  Subscription

   has following fields:

   - `name' - short name

   - `description' - longer description

   - `price' - subscription price

   - `recurrence_period' - PayPal subscription recurrence period (used

     only if `recurrence_unit' is not `None')

   - `recurrence_unit' - in what units is recurrence period expressed:

     - D for days

     - W for weeks

     - M for months

     - Y for years

     - None (NULL) for one-time (non-recurring) payment

   - `group' - one to one relation to

     `django.contrib.auth.models.Group'.  Subscription is identified

     by the group.

3.1.1 methods

-------------

    - `price_per_day()' - returns estimate subscription price per day,

      as a float.  This value is used to give user that upgrades

      subscription a rebate for unused part of month.  Value is only

      an estimate: average length of month (30.4368 days) and year

      (365.2425 days) are used.

    - `get_pricing_display()' - return pretty pricing info for display

      as a string.

3.2 UserSubscription

====================

   This model instances define a user's subscription.  Model has

   following fields:

   - `user' - one-to-one relation to `auth.User' model, primary key;

   - `subscription' - foreign key relation to `Subscription' model,

     specifies kind of subscription `user' is subscribed to;

   - `expires' - expiry date (if null, subscription never expires)

   - `active' - boolean, True if subscription is active

   - `cancelled' - boolean, True if subscription was cancelled

   Fields `active' and `cancelled' are used for implementing the

   subscription change flow (see later).  Every UserSubscription

   starts with both `active' and `cancelled' set to `False'.  When

   PayPal subscription is confirmed, `active' is set to True.  When

   any other PayPal subscription for the same user is confirmed,

   `active' is set to `False' (because `active' is set to `True' for

   this other subscription, in other UserSubscription instance).  When

   subscription is cancelled at PayPal, `cancelled' is set to `True'.

   When UserSubscription is cancelled and not active, it is deleted.

   When UserSubscription has expired and is cancelled, it is deleted.

   Transition graph of these state bits can be found in

   [file:docs/usersubscription-states.dot.png] (GraphViz source in

   [file:docs/usersubscription-states.dot]).

   Class field `grace_timedelta' is provided (read-only) and contains

   effective value of `SUBSCRIPTION_GRACE_PERIOD' setting as

   `datetime.timedelta' object.

3.2.1 methods

-------------

    - `user_is_group_member()' - returns true if `user' is member of

      `subscription.group';

    - `expired()' - returns true if there is more than

      `SUBSCRIPTION_GRACE_PERIOD' days after `expires' date;

    - `valid()' - returns true if:

      + `expired()' is false and `user_is_group_member()' is false, or

      + `expired()' is true and `user_is_group_member()' is true;

    - `unsubscribe()' - remove `subscription.group' from `user''s groups

    - `subscribe()' - add `subscription.group' to `user''s groups

      (called automatically on PayPal one-time payment and

      subscription start);

    - `fix()' - if not `valid()', call `unsubscribe()' or `subscribe()';

    - `extend(timedelta=None)' - extend `expires' field by provided

      `datetime.timedelta', or by `subscription''s recurrence period

      (called automatically on PayPal subscription payments);

    - `try_change(subscription)' - sends `change_check' signal to test

      whether change from `self.subscription' to Subscription object

      supplied in `subscription' parameter is possible.  Returns list

      of reasons why upgrade is denied; if list is empty, upgrade is

      allowed.

    Convenience function `subscription.models.unsubscribe_expired()'

    is also provided.  It loops over all expired `UserSubscription'

    instances and calls `unsubscribe()' method.  It is intended to be

    called automatically from cron, django-cron, or on some event.

    Alternatively, `fix()' can be called on events related to

    user, e.g. on user login.

3.3 Transaction

===============

   `Transaction' model is mostly read-only and is used to view

   subscription-related events in the admin panel. It has following

   fields:

   - `timestamp' - date and time of event

   - `subscription' - foreign key of `Subscription' model that event

     was related to

   - `user' - foreign key of `django.contrib.auth.models.User' model

     that event was related to

   - `ipn' - foreign key of `paypal.standard.ipn.models.PayPalIPN'

     model identifying payment callback related to event

   - `event' - type of event, one of:

     - new usersubscription

     - one-time payment

     - subscription payment

     - unexpected payment

     - payment flagged

     - deactivated

     - activated

     - unexpected subscription

     - remove subscription

     - cancel subscription

     - unexpected cancel

     - modify subscription

     - subscription expired

     The "unexpected" events are ones that could not be related to any

     specific user/subscription pair.

   - `amount' - amount (`mc_gross') of `ipn'

   - `comment' - site admin's comment, only field intended to be

     modified.

   In admin panel's `Transaction' object list, fields `subscription',

   `user', `ipn' are links to related modes instance's admin forms.

4 Signals

~~~~~~~~~

  On subscription-related events, the application sends signals that

  project code can connect to and do some site-specific things (e.g.

  send a nice e-mail to user).  Signals are available in

  `subscription.signals' package.  All signals have `Subscription'

  instance (or, in extreme cases with `event' signal, `None') as

  sender, and have arguments `ipn'

  (`paypal.standard.ipn.models.PayPalIPN' model instance), `user'

  (`django.contrib.auth.models.User' instance), `subscription'

  (`Subscription' instance or None, same as sender),

  `usersubscription' (`UserSubscription' instance).  Signals are:

  - `signed_up' - user signed up for one-time payment,

  - `subscribed' - user subscribed

  - `unsubscribed' - user unsubscribed from PayPal (`usersubscription'

    is a deleted object if `usersubscription.active' is True)

  - `paid' - payment received from a subscription

  - `event' - other strange event, does not receive `usersubscription'

    argument (there is no meaningful `UserSubscription' object) and

    receives additional `event' argument, which may be

    - `unexpected_payment'

    - `flagged'

    - `unexpected_subscription'

    - `unexpected_cancel'

   - `subscription_modify'

  Signal `change_check' is a hook for verification of subscription

  change.  Sender is `UserSubscription' object with user's current

  subscription, additional parameter `subscription' provides

  subscription to change to.  If subscription change is possible,

  listener should return `None', otherwise it should return a string

  describing reason that will be displayed to user.

5 Views

~~~~~~~

  Views are available in `subscription.views' module

  - `subscription_list' lists available subscription using

    `subscription/subscription_list.html' template

  - `subscription_detail' presents details of the selected

    subscription (login is required for this view) along with PayPal

    button for subscription or upgrade.

6 URLs

~~~~~~

  Module `subscription.urls' configures default urls for module.  This

  are:

  - root URL displays `subscription_list' view

  - /id/ (numeric ID) displays `subscription_detail' view for

    Subscription with ID /id/

  - `paypal/' is PayPal IPN URL

  - `done/' displays `subscription/subscription_done.html' template

    and is where successful PayPal transactions for initial

    subscription are redirected

  - `change-done/' displays

    `subscription/subscription_change_done.html' template and is

    where successful PayPal transactions for subscription change are

    redirected

  - `cancel/' displays `subscription/subscription_cancel.html'

    template and is where cancelled PayPal transactions are redirected

7 Templates

~~~~~~~~~~~

  Templates `subscription/subscription_done.html' and

  `subscription/subscription_cancel.html' receive no context.

  Template `subscription/subscription_change_dane.html' receives

  `cancel_url' parameter, which is URL to PayPal list of transactions

  with site's merchant account, making it easier to cancel the old

  subscription.

  Template `subscription/subscription_list.html' receives

  `object_list' variable which is a list of `Subscription' objects.

  Template `subscription/subscription_detail.html' receives:

  - `object' variable which is a `Subscription' object,

  - `usersubscription' variable, which is current user's active

    `UserSubscription' instance (may be used to tell apart initial

    subscription from subscription change/upgrade, or to display

    current subscription's expiry date),

  - `change_denied_reasons', which is a list of reasons that

    subscription change/upgrade is denied; if false (empty list or

    `None' if user is not subscribed), change or signup is allowed,

  - `form' variable which is a PayPal form for the `object', if

    `change_denied_reasons' is false,

  - `cancel_url', which is URL to PayPal list of transactions with

    site's merchant account, making it easier to cancel the old

    subscription.

8 Subscription change

~~~~~~~~~~~~~~~~~~~~~

  Most complex flow in this app is when user wants to change (upgrade)

  current subscription.  For subscriptions we are using PayPal

  standard subscriptions API.  This means, we get three kinds of

  asynchronous IPN notifications:

  - subscr_signup when user signs up for new subscription,

  - subscr_payment on every single payment,

  - subscr_cancel when user or merchant cancels subscription (or

    subscr_eot when time-limited subscription runs out; we treat

    subscr_eot exactly as subscr_cancel).

  When user signs up, we get subscr_signup and subscr_payment for

  first payment, in random order.  There is no support for changing

  running subscription, so user needs to sign up for new subscription

  and cancel old one.

  Events for subscriptions are handled this way:

  - subscr_payment finds UserSubscription object for User and

    Subscription ID specified in the IPN.  If UserSubscription is not

    found, new one is created, which becomes inactive.  Found or new

    UserSubscription object is extended for the next billing period.

  - subscr_signup finds UserSubscription object for User and

    Subscription ID specified in the IPN.  If UserSubscription is not

    found, new one is created.  Found or created UserSubscription is

    set to active, User is added to subscription's group; if user has

    another UserSubscription, they are made inactive and user is

    removed from these Subscription groups.  In effect, on signup the

    new subscription becomes user's only active one, and its group

    only subscription-related group to which user belongs.

  - subscr_cancel finds relevant UserSubscription object.  If it is

    inactive (which means subscription change), removes user from its

    subscription's group, and deletes the UserSubscription.  If it is

    active, does nothing, so user can use up rest of current billing

    period.

  So, signup flow is:

  - user clicks in PayPal subscribe button displayed on subscription

    detail page and subscribes at PayPal,

  - subscr_payment extends the UserSubscription,

  - subscr_signup makes the UserSubscription active and uncancelled

    and adds user to group,

  - whichever of those got called first, creates the UserSubscription.

  Cancel flow is:

  - user cancels subscription at PayPal,

  - UserSubscription is active, so it is marked cancelled, kept and

    stays valid until expiry.

  Subscription change flow is:

  - If user is allowed to change subscription, subscription detail page

    displays PayPal subscribe button,

  - user clicks subscribe button and signs up for new subscription at

    PayPal,

  - landing page after PayPal transaction displays link to PayPal

    transaction list which user can use to cancel old subscription at

    PayPal,

  - user cancels old subscription at PayPal;

  - whichever of subscr_payment or subscr_signup gets called first,

    creates new, inactive, uncancelled UserSubscription instance,

  - subscr_payment extends new UserSubscription instance for next

    billing period,

  - subscr_signup deactivates all active UserSubscriptions and removes

    user from group; then, activates and uncancels new

    UserSubscription and adds user to its subscription's group,

  - subscr_cancel (which gets called after previous two, because user

    needs some time to click through the PayPal forms) finds inactive

    UserSubscription, ensures that user is really not member of group,

    and deletes the UserSubscription object.

  If user makes a mistake and cancels new subscription instead of the

  old one, new subscription goes through "Cancel flow" above, does not

  get deleted, so user has chance to fix things at PayPal.  Project

  should add `signals.unsubscribed' handler that would detect such

  situation (if `usersubscription' parameter is active, and user has

  inactive UserSubscription objects, cancel was probably a mistake)

  and notify user of his mistake.

9 Example code

~~~~~~~~~~~~~~

  Example usage and templates are available as `django-saas-kit'

  project at [http://github.com/saas-kit/django-saas-kit/]

10 Bugs and omissions

~~~~~~~~~~~~~~~~~~~~~

  - There is no `setup.py' script for automated installation.

  - No support for PayPal PDT; PDT has only presentational value (IPN

    needs to be received anyway, and PDT should be used only to

    display transaction details to user on after transaction landing

    page), so support for it has been intentionally omitted.

10.1 Plans

==========

  - Single payments for subscription, including possibility of

    pay-as-you-go scheme

11 License

~~~~~~~~~~

  This project is licensed on terms of GPL (GPL-LICENSE.txt) licenses.