Subscriptions

Membership Subscriptions are an amazingly powerful and popular feature of Charge.

You can use subscriptions to build really complex paid subscription access systems, and the setup is quick and painless.

Upgrade to Pro Subscriptions are a pro only feature. If you're using the free edition you'll need to upgrade to pro to use them

How they work #

Membership Subscriptions' key feature is the active user group. When Craft users are added to a subscription they are added to the active user group for that subscription. In addition, if their payment is set to be recurring, when it later ends or fails, they'll be removed from that group.

To build an access limited member site, you'd just need to set any permissions against that member group, and add checks at your template level similar to : {% if currentUser.isInUserGroup %}.. or {% if currentUser.hasPermission %}..`

Setup #

Membership Subscriptions have a few basic setup features :

Name
The name of this subscription. This will be how the subscribers are shown in the CP
Handle
The handle for the subscription. This will be how the subscription is referenced in your templates.
Active User Group
The active user group for the subscription. When a user joins a subscription they'll be added to this group. When they leave they'll be removed from this group
Welcome Email
The email that's sent when a user joins a subscription
Recurring Email
The email that's sent whenever a user's recurring payment is paid
Failure Email
The email that's sent when the user leaves the subscription
Enabled
If this subscription is enabled for new users to join

Not just for recurring payments Subscriptions work just as well for customer with one-time payments, not just recurring payments

Adding Users to Subscriptions #

Trigging the addition of a user to a subscription is very simple, and uses the onSuccess option as part of the setPaymentOptions() method.

If we had a subscription with a handle of gold-membership we could add this to our payment form like so :

Webhooks are required The recurring and failure states of subscriptions are all triggered using the web hook events. Make sure you've got them setup properly to make proper use of Subscriptions

{% set options = {
    'planAmount' : 5.99,
    'planInterval' : 'month',
    'planIntervalCount' : '1',
    'actions' : {
        'onSuccess': {
            'subscription' : 'gold-membership'
        },
    }}
%}

{{ craft.charge.setPaymentOptions(options) }}

In the above example we'll have the User added to the gold-membership subscription when the payment is successful. This payment plan is for a monthly payment of $5.99. When that later fails or ends, this will trigger the failure state on the subscription, which will remove them from the active user group on the subscription.

It's that simple!

Viewing Subscribers #

When you have at least one Subscription setup with Charge you'll see a new area in the Charge CP called Subscribers. In here you'll see all the active subscriptions for your members.

In addition, the subscription details will be shown for the customers on the Charge details too.

Offering Multiple Subscription Choices #

It's a very common setup to offer customer the choice of multiple plans. With Charge and the ability to pass multiple plan choices that's really simple too.

For example, we might have a bronze, silver and gold membership system, each with different price levels. To that up on a single Charge form we'd just do something like this :

{% set options = {
    'planChoiceDefault': 'gold',
    'planChoices' : {
        'gold' : {
            'label': 'Gold Plan - $599 / year',
            'planAmount' : 599,
            'planInterval' : 'year',
            'planIntervalCount' : 1,
            'actions' : {
                'onSuccess': {
                    'subscription' : 'gold'
                },
            },
        },
        'silver' : {
            'label': 'Silver Plan - $99 / month',
            'planAmount' : 99,
            'planInterval' : 'month',
            'planIntervalCount' : 1,
            'actions' : {
                'onSuccess': {
                    'subscription' : 'silver'
                },
            },
        },
        'bronze' : {
            'label': 'Bronze Plan - $49 / month',
            'planAmount' : 49.99,
            'planInterval' : 'month',
            'planIntervalCount' : 1,            
            'actions' : {
                'onSuccess': {
                    'subscription' : 'bronze'
                },
            },
        }
    }
} %}
{{ craft.charge.setPaymentOptions(options) }}

..

 {{ forms.radioGroupField({
        label: 'Plan Choice',
        name: 'planChoice',
        id: 'planChoice',
        options: options.planChoices,
        value: (charge is defined ? charge.planChoice),
        errors: (charge is defined ? charge.getErrors('planChoice'))
}) }}

There are two key things to note on this setup :

  1. We can pass multiple sets of options via the planChoices option
  2. We let the customer choose their specific plan with an input named planChoice, and default to gold using the planChoiceDefault option

To allow your customers to modify or end their subscriptions from the front-end, Check out the options for self-service