Module Overview

This module creates three content entities.

Billing Plan Entity

It serves three purposes

1. Creates a template from which to create subscriptions. The template contains the following information, which is copied to subscription entities created from a purchase of this billing plan:
   • Which Drupal Roles to grant a subscriber.
   • Which Drupal Roles to revoke when the subscription has expired.
2. Presents pricing and a description of the plan to users.
3. Contains the Braintree Plan ID of the plan in the Braintree Console. The price entered in the Braintree Console is the price that will be charged. Prices entered on the Billing Plan entity are for display purposes only.

Subscription Entity

• References a user entity.
• Records the status of a user's subscription.
• Records the Braintree subscription ID provided by the Braintree API. This is used to find the subscription when a webhook is received from Braintree notifying that the subscription has expired.
• When a user cancels their subscription, if they gave a reason for cancelling, this is recorded on the subscription entity.

Changes to a billing plan have no effect on Subscription entities created by that plan. If the Drupal Roles granted or revoked are adjusted for a Billing Plan from which Subscription entities have already been created, then if those same adjustments are needed for those existing subscriptions then each subscription would need to be manually edited.

Discount Entity

• Enables a fixed amount coupon code to be entered at checkout.
• The coupon code is valid only for Billing Plan Entities that the Discount Entity references.
• Contains the ID of the discount in the Braintree Console.

Concepts

• A user's subscription can have one of two statuses: "active" or "canceled".
  • When a user's subscription is set to canceled, the Drupal Roles configured on the subscription are revoked from the user.
  • When a user cancels their subscription, the boolean "Cancel at period end" is checked. Their subscription status is not immediately changed to "canceled", since the user should be entitled to their premium Drupal Role until the end of the current billing period. Since the Braintree payment gateway doesn't natively support the concept of "Cancel at period end", Braintree Cashier edits the subscription on Braintree via the Braintree API to change the number of billing periods to equal the current billing period, such that it will expire at the end of the current billing period. This is the workaround used by Laravel's Cashier Braintree project.
• Free Trials:
  • When a user cancels a free trial, the corresponding subscription at Braintree is canceled in order to avoid billing at the end of the free trial.
  • The user's local subscription entity is still active so that the user still has premium roles until the end of the original free trial period. The subscription entity is set to cancel at period end, and the period end date is recorded from the nextBillingDate property of the Braintree subscription. The local subscription entity is canceled by cron after the period end date.
  • If a user with a currently active free trial subscription that is set to cancel at period end signs up for a new subscription that also has a free trial, the free trial period of the new subscription is reduced by the number of days elapsed on their first free trial. This proration of the new free trial period is intended to avoid what would otherwise be never ending free trials for users that cancel and then sign up again.