Subscriptions Version 4.3.1

About CartThrob Subscriptions

CartThrob Subscriptions gives your CartThrob powered website the ability to take recurring payments, for things like membership, layaway, monthly donations, and more. CartThrob Subscriptions is an add-on for CartThrob that requires the ExpressionEngine CMS. Like other CartThrob addons, it must be uploaded and installed on your website, and CartThrob must be active for it to run.

To use this addon, you will need to add additional template tags for adding, editing, deleting subscriptions, and adding subscription items to the cart. You can place the tags in any of your EE templates to suit your specific workflow. Sample template code can be found here in the documentation as well as included with the Subscriptions add-on.

CartThrob Subscriptions contains robust capabilities to generate and maintain recurrent billings (subscriptions) for customers, maintain customer permissions, customer data token vaults, and more.

There are five key parts of CartThrob Subscriptions

Recurrent Billing
Ad hoc Billing
Vault/Tokens
Permissions system
Per Member Customization

The primary feature that you may be interested in is the recurrent billing portion of this module. You can set up subscription products that contain start and end dates, trial prices, the number of times the rebill should occur and whether or not the subscription should expire.

A secondary feature of CartThrob Subscriptions is ad hoc billing. Ad hoc billing allows Subscription customers to be billed for arbitrary charges manually, all within CartThrob. View your Subscribers, select which you want to charge, and fill out a simple form which includes the amount. Orders are processed as usual and the Customer is notified.

The third portion is the data vault / token based billing portion. CartThrob uses your gateway to store sensitive data, offloading the responsibility & liability onto the gateway provider, so NO CREDIT CARD details are stored locally.. CartThrob uses the customer token to initiate a charge on a time basis that you specify. Permissions is the fourth portion of CartThrob Subscriptions. Permissions allows you to create and sell access to content on your site. You can use the permissions system to sell one or more access levels per transaction which will allow you to selectively show content to a user based on previous purchases.

The fifth feature allows for Customer specific customization of Plans. While the majority of Customers will fit within specific buckets that Plans were built for, others may require unique customization specific to that Customer. Every data point within a Plan can be set or changed on a per Customer basis to allow for maximum flexibility.

Note Membership is required to purchase a subscription, though login is not required in advance of making the purchase. If a user is not logged in, and purchases a subscription, a member will automatically be created, even if maintaining membership on your site is not necessary.

How CartThrob Subscriptions Works

It's important to think of CartThrob Subscriptions as a collection of tools to allow for automated billing, management systems, and template tags. The management tools are pure ExpressionEngine Add-ons, but the template tags and automated billing will require some elbow grease on the development front; those have to be setup per your requirements.

At the most basic, a Subscription flow would look like the below:

A Subscription Plan is added to the cart.
The customer checks out, during which time your payment gateway is told to store the customer's credit card information in their vault system in exchange for a "token" that will be stored by CartThrob (rather than the customer's information). PCI Compliance is good.
The initial subscription costs are billed immediately, and the subscription details are stored in CartThrob for future rebill attempts.
CartThrob Permissions (if any) related to the Subscription Plan are stored and assigned to the user
Customer transaction is complete
If configured, the Customer is notified that they've made a successful transactions via email

In future rebill attempts:

The Rebill System is used to check for Subscriptions that need rebilling. You can set your CRON to fire as often as you'd like, or use the included Command Line tool, but generally one time a day is all that is required.
If an item needs rebilling, CartThrob Subscriptions will initiate a new Order and attempt to complete the transaction using the Token provided by your gateway.
1. If the transaction is successful, the Subscription will be updated.
2. If not, CartThrob will put the subscription on hold and attempt to rebill the subscription until it is successful, or until the token is invalidated by the gateway, or until Max Rebill attempts is met.
CartThrob subscription orders are placed like standard orders, and will show up in the customer's order history. Standard order emails will also be sent in the case of a successful transaction, or in case of failure.

Walled Garden Content:

If your site needs it, CartThrob Subscriptions provides a number of ExpressionEngine compatible template tags you can use.
All Subscription based tags will ensure the Subscription is active and available allowing for control over select templates

Seeder Compatible

CartThrob Subscriptions includes a number of Seeder Seeds to allow developers to get a head start on their website by creating:

Subscriptions
Plans
Permissions
Vaults

Features

Create recurring subscription payments in addition to product & donation payments
Simple setup
Email notifications for purchase, rebill success, hold and failure events
Create and sell permissions (ACL-access control levels) to pay for access to content
Customers can update their own subscriptions (if configured to allow)
Works with many popular payment gateways including Stripe and Authorize.net
Uses token/vault based payments. No credit card data is stored on your site.
Create ad hoc payments against Customer accounts
Provides a Plan based mechanism to granularly control your Subscriptions
Setup and management of trial subscriptions on a per day basis
Prorated refunds and account balancing upon Cancellation

Installation

Installing CartThrob Subscriptions really boils down to a few steps:

Installing and configuring the Addon
Setting up Subscription Notifications within CartThrob
Setting up Rebilling

Requirements

ExpressionEngine 6.2+
CartThrob 6.3+
PHP 7.4+

Installing the Addon

This done just like any other ExpressionEngine Addon:

Upload the /system/user/addons/cartthrob_subscriptions/ folder to /system/user/addons/
Make sure Extensions are enabled on your system
Install the CartThrob Subscriptions module and extension (through EE's add-ons/modules panel)

Note that CartThrob Permissions (included) is required to be installed alongside CartThrob Subscriptions

Once CartThrob Subscriptions has been installed, please note that you will need to

Configure notifications through CartThrob's notification settings (Add-ons » CartThrob » Notifications)
You must set up an automation method so that CartThrob Subscriptions can rebill your customer's token accounts. For more on setting up an automation method, please review the instructions below

By adding CartThrob Subscriptions, you will notice

A new Control Panel view that allows for management of all Subscription based data.
It adds new notifications to CartThrob's notifications panel.
It adds a new subscriptions fieldtype to EE's addons » fieldtypes fields

Upgrading

Upload the /system/user/addons/cartthrob_subscriptions/ folder overwriting existing files.
Within your ExpressionEngine Control Panel, go to Add-ons » Updates » and update CartThrob Subscriptions

Sample Templates

CartThrob Subscriptions includes some starter templates you can use to get a head start on setting up your site and to provide examples. They included everything your site can make use of under the subscriptions template group.

Note that the Sample Templates have a HARD requirement on the included CartThrob Sample Templates. They'll still work but it'll have UI/X issues.

Account Management
Cancel Subscription
Change Plan
Checkout

Installation

If you want to install the templates manually, you can find them within the Subscriptions Add-on at cartthrob_subscriptions/installer/templates.

Settings

CartThrob Subscriptions has settings for

Maximum Rebill Attempts
Charge tax on subscription rebills?
Charge shipping on subscription rebills?
Add discounts to subscription rebills?

Notifications

When CartThrob Subscriptions addon is active, it adds additional notification options to CartThrob's notifications settings. Using CartThrob's Notification settings you can specify a standard EE template that will be emailed to the customer when one of several events occurs.

rebill_success Sent when account has been rebilled
rebill_failure Sent when account rebill has failed
rebill_final_failure Sent when last rebill attempt has failed
rebill_hold Sent when account rebill has been placed on hold due to failure or final failure.
subscription_cancelled Sent when a Subscription is canceled
subscription_expired Sent when a Subscription has reached the end date for its term
subscription_exhausted Sent when a Subscription has been renewed the maximum number of times
manual_bill Sent when you have manually billed a customer

Each of these notifications can be mapped to an ExpressionEngine template that you can create using standard EE template system and template tags. Each of the notification templates above, can use the following variables:

Notification Variables

You can use all the Variables provided by the subscriptions template tag.

Setting up rebilling

Rebilling is handled through either a Cron command, to ping CartThrob every XX YY, to process any Subscriptions with billing due or, ideally, as a Systemd Service on the host system.

Note that the above "ping" is directly tied to the Max Rebill Attempt Setting, so is considered best practice to run it once per day. This would allow your Rebill Attempt Setting to essentially be a per day number.

Rebill Command

To execute the Rebill Command call:

eecli.php cartthrob:subscriptions:rebill

There are 2 Command Line options available:

--service / (-s) boolean

Run this command as a Service rather than via Cron or Terminal. Default is no

--tune / (-t) integer

The amount of time in seconds to pause execution between iterations. Default is 86400

Systemd Config File

CartThrob Subscriptions includes a basic .service file that will allow Rebill to work as a Service (Linux with Systemd only). You can find it at cartthrob_subscriptions/lib/systemd/system.

Legacy `extload` Method (deprecated)

NOTE the extload method is deprecated and will be removed by Subscriptions 5.0. Use the Rebill Command instead.

Rebilling requires that your system be told to periodically check for expired and expiring subscriptions. Rebilling is handled with CartThrob through

In the CartThrob subscription settings, the CRON commands necessary to automate the rebiling process are displayed specific to your installation on your host. Generally, you will need to either contact your hosting company to add those commands, or using your hosting control panel, you will need to set up a CRON job using those commands. Essentially, once you've figured out where you can add CRON jobs, you just need to copy the command from the subscriptions settings page, paste it, and save the CRON job.

Note We do not provide free support for CRON configuration. If you need assistance setting up CRON, please contact us, and we can assist you in setting it up at our standard hourly rate.

Our CRON methods make use of a file called extload.php in themes/user/cartthrob/lib. If you have changed the location of your system folder, you will need to update extload.php with the location of your system folder.

There are several methods available on most systems to run CRON.

If you can execute shell scripts on your server:

/your/server/path/to/themes/user/cartthrob/lib/cron_subscriptions.sh /server/path/themes/user/cartthrob/lib/extload.php
If you can run perl scripts on your server:

/your/server/path/to/themes/user/cartthrob/lib/cron_subscriptions.pl /server/path/themes/user/cartthrob/lib/extload.php
If your server allows the use of PHP's "passthru" function: /your/server/path/to/themes/user/cartthrob/lib/extload.php cron process_subscriptions
You can also manually call your rebill URL manually. (the URL is listed in your settings page)
Or it can be called via CURL curl --silent "your url" 2>&1 /dev/null

It may be easiest, if you are unfamiliar with CRON to contact your hosting company and ask them the best way to set up CRON, or request that they set it up for you. Using the provided scripts, it should be fairly straightforward to add.

Setting up the FieldType

NOTE that the Subscriptions FieldType is deprecated and will be removed at 5.0. It's provided purely for legacy customers and should NOT be implemented anew.

Install the CartThrob Subscriptions FieldType through (through EE's addons/fieldtypes panel)
Go to the admin » channel » channel fields settings
Choose your product channel fields group (you may add this to multiple channel field groups) and add this field type to this field group.

Once the FieldType is installed, and set up in a channel field group, the related channel will now have the option of setting up subscription options for each individual entry in that channel. When you add subscription options for an entry, those options are not set globally, meaning that when you later update those options, it will not affect current subscriptions originally based on the same entry. If you would like to use global subscription plans, please add them in the CartThrob Subscriptions Admin Panel.

General User Flow

A standard item is added to the cart, along with parameter that identifies it as a subscription item, or an entry with a subscriptions field type is added to the cart.
The customer checks out, during which time your payment gateway is told to store the customer's credit card information in their vault system in exchange for a "token" that will be stored by CartThrob (rather than the customer's information)
The initial subscription costs are billed immediately, and the subscription details are stored in CartThrob for future rebill attempts.
Permissions related to the subscription are stored
Customer transaction is complete
Customer is notified that they've made a successful transactions via email

In future rebill attempts:

CRON is used to check for subs that need rebilling. You can set your CRON to fire as often as you'd like, but generally a few times a day is all that is required.
If an item needs rebilling, CartThrob will initiate a new order and attempt to complete the transaction using the Token provided by your gateway. If the transaction is successful, the order will be updated. If not, CartThrob will put the subscription on hold and attempt to rebill the subscription until it is successful, or until the subscription is cancelled by the gateway.
CartThrob subscription orders are placed like standard orders, and will show up in the customer's order history. Standard order emails will also be sent in the case of a successful transaction, or in case of failure.

Key Concepts

Subscription System

A subscription (or recurrent bill) is simply a contract between the customer and your site that allows you to initiate a payment on the customer's behalf on a regular basis. You can use:

Parameters to create subscriptions on the fly
An administrative interface for creating subscription products via the backend.

The subscription module allows you to create and manage subscriptions.

Token Vaults System

Most payment gateways have systems that can store customer information (including credit card numbers) securely on their systems so you don't have to. The benefits of using a vault system is that your PCI Compliance burden is lessened... basically you don't have to be responsible for storing customer billing information. Generally when adding a customer to the vault system, you capture a token from the payment gateway itself. Once you have this payment token, it can be sent in the future to initiate a payment even without the customer present, and without storing customer information.

Uses of vault systems

To initiate payments in a subscription on a regular basis without the customer present
To make it simple for your customer to store their checkout information on your site so that they don't have to enter it every time they checkout (includes the storing of credit card numbers)

CartThrob's subscription system requires that you use a payment gateway that can handle Vault/Token based transactions. This ensures you don’t have to store any credit card details on your server, and not incur the overhead and expense of securing those. Currently, CartThrob supports the following gateways that offer Token based transactions:

Authorize.net (CIM)
Stripe

To use any one of these systems, your gateway account needs to include basic services PLUS the specific token/vault service listed above active on the account. Generally once the service is active, you need take no further action.

If you would like us to support any additional gateway provider please contact us.

Permissions System

When adding items to the cart, it's possible to assign "permissions" to the user. These permissions remain in place until removed. Once a permission is set you can use the permissions tag to protect content from being accessed by customers that do not have an assigned permission. Permissions have no effect on ExpressionEngine's backend access or other member group options and are only available for the front end of your website.

Administration

Once customers have purchased subscriptions, you may need to review and administer those subscriptions. The CartThrob Subscriptions Manager includes an administrative interface for managing subscribers and their subscriptions, adding additional charges to a single customer, and creating new subscription plans for purchase.

Administering Plans

Most Subscriptions start with a Plan. You CAN create ad hoc Subscriptions though that’s an edge case; usually you’ll start with a Plan. So, what’s a Plan?

Simply, a Plan is an outline for how a Subscription behaves. A Plan lays out the billing schedule, how much is billed per cycle, any Permissions provided upon Subscription, and whether the Plan can be modified by the Subscriber before purchase.

Note that Subscribers can be connected to multiple Plans though they must be purchased separately.

Create a Plan

To Create A Plan, at a minimum, you need a Name and a Price (even if that Price is "0"). You can setup the Occurrence intervals, whether there's a Trial Setting, and the Permissions (if any).

Create a Plan

View Existing Plans

All Plans are listed, using pagination, and allow easy access to manage.

Viewing Existing Plans

Remove Plan

Removing a Plan is not something to be taken lightly. Existing Subscriptions with said Plan will continue to function though editing will require a new Plan assignment.

Remove Plan

Administering Subscriptions

Once a user purchases a Plan, they’re now considered a Subscriber with an associated Subscription. Basically, a Subscription is just a container that is a copy of a specific Plan, that can be administered through your ExpressionEngine website.

You can create Subscriptions for Customers, through the site Control Panel, though that Customer WILL require a valid Vault connected to their account in order to be billed after the first cycle.

While viewing all Subscriptions, you can select individual ones to force the rebill cycle to renew along with a custom price for said rebill. Note that forcing a rebill WILL reset their next rebill date/time so use caution.

Create a Subscription

Creating a Subscription allows for granular customization though any Settings not entered will default to the Plan value.

In order to Create a Subscription in the Control Panel, you must enter a valid Member ID and that Member MUST have a valid Vault if you intend on Charging upon creation.

Create a Subscription.

View Existing Subscriptions

All existing Subscriptions are displayed with quick links to management tools.

Viewing Existing Subscriptions

Edit Subscription

Editing a Subscription allows you to break it away from the Plans mold. You can set custom options, on a per Subscription basis, to allow for specific customizations.

Note that when editing a Subscription, all its child data (Vault, Member, etc) are locked to the given Member. You'll only be able to choose Vaults for that Member and Orders owned by that Member.

Edit Subscription

Charge Next Billing

At any time, you can Charge your Subscriptions renewal manually.

Charge Next Billing

Cancel Subscription

Depending on how you handle Cancellations, this behaves differently.

If you Refund any difference back to the Customer, the Subscription is canceled immediately and the Customer will no longer have access
If you do NOT Refund any difference, the Subscription will end at the term defined by the Subscription.

Cancel Subscription

Administering Subscribers

Several new tags are available for use with CartThrob Subscriptions, and several existing tags have new parameters. It’s highly recommended to install the example templates and channels included within Subscriptions to get an idea of how best to set up your system.

Add to cart form and checkout form parameters

add_to_cart_form and checkout_form share the following parameters in addition to standard parameters associated with them.

Note Any item added to the cart that is set as a subscription item will be overridden if the checkout form also uses subscription parameters. In that case, the entire cart contents will be rebilled on a regular basis.

subscription_plan_id (this is applicable to add_to_cart_form only)
subscription
subscription_allow_modification
subscription_interval_units
subscription_interval
subscription_end_date
subscription_start_date
subscription_trial_occurrences
subscription_price
subscription_trial_price
subscription_total_occurrences
subscription_name
permissions
options:subscription_interval_units

`subscription_plan_id`

This applies to global subscription plans that have been created in CartThrob Subscription Admin panel. If this value is set, all other parameters related to subscription length will be ignored.

CartThrob Subscriptions Admin control panel includes the ability to add global subscription products. These subscription products are global, any changes made to them are made globally to all customers that have purchased these plans. To sell one of these plans, you must set the subscription_plan_id parameter in the add_to_cart_form

{exp:cartthrob:plans}
    {exp:cartthrob:add_to_cart_form 
        return=""
        subscription_plan_id="{id}"
        entry_id="{entry_id}"
        }

    <input type="submit" value="Add to Cart" />

    {/exp:cartthrob:add_to_cart_form}
{/exp:cartthrob:plans}

NOTE The previous example also made use of the plans tag

`subscription`

Boolean. Set this to yes if you want the item added to the cart to be processed as a recurrent bill/subscription. Defaults to no if not set.

subscription="yes"

`subscription_allow_modification`

Boolean. Set this to yes if you want the customer to be allowed to modify the details of this subscription later. Defaults to no if not set.

subscription_allow_modification="yes"

`subscription_interval_units`

This is the rebill period. Acceptable values are years, months, weeks, days. Defaults to "months" if not set.

subscription_interval_units="months"

`subscription_interval_length`

This is the rebill periodicity. Generally this will be 1 (for once a month). By default it will be 1.

subscription_interval_length="1"

`subscription_start_date`

This is the start date of the subscription, set as a unix timestamp. Defaults to the current day if not set.

subscription_start_date="1320596025"

`subscription_end_date`

This is the end date of the subscription, set as a unix timestamp. Optional.

subscription_end_date="1320596025"

`subscription_price`

This is an amount that should be billed as the amount. If left blank and using with a product, it will assume the product price.

subscription_price="1"

`subscription_total_occurrences`

This is the total number of times a subscription should be billed. The initial charge counts as the first billing occurrence, if there is no trial period. Defaults to 1, which means no future rebilling, so you should set this one. Set it to 0 to incur infinite rebills.

subscription_total_occurrences="1"

`subscription_trial_price`

This is an amount that should be billed as a trial amount. Optional.

subscription_trial_price="1"

`subscription_trial_occurrences`

This is the number of times a trial amount should be billed. The initial charge counts as the first trial billing occurrence.

subscription_trial_occurrences="1"

`subscription_name`

This is the name of the subscription for reference. The value is arbitrary. If left blank, it will be set to the title of the item being added to the cart, or a generic "subscription" if set at checkout without a title.

subscription_name="My title"

`permissions`

These are the permissions associated with the item being added. Privileges can be associated with or without subscriptions being in place. Separate individual permissions by a pipe | character.

permissions="1|3|5"

`options:[your_parameter_name]`

All of the subscription parameters described above can be also be set via form inputs. For instance, you may want your users to be able to select the number of total billing occurrences in a dropdown. Use the options: parameter / tag pair and CartThrob will safely encrypt the selectable options.

options:subscription_total_occurrences="12:1 Year|24:2 Years|36:3 Years"

And inside the form,

<select name="subscription_total_occurrences">
    {options:subscription_total_occurrences}
        <option value="{option_value}">{option_name}</option>
    {/options:subscription_total_occurrences}
</select>

`update_cart_form`

This refers to cartthrob's standard update_cart_form. CartThrob Subscriptions extends the update_cart_form to include new functionality.

Parameters

in addition to standard parameters associated with update_cart_form the subscription parameter is also available. Though subscription details can't be updated once the item has been added to the cart, any item in the cart can be converted to and from a subscription item. This is useful where you might add a donation to the cart, and later give the purchaser the option to convert it to a recurring bill. If you need to update other subscription details for an item once in the cart, the item will need to be removed and re-added.

`subscription`

subscription="no"

`subscriptions`

This tag outputs data about existing subscriptions.

Parameters

`id`

The subscription id

id="123"

`order_id`

The order id that was initially used to generate the subscription.

order_id="123"

`member_id`

Member id of the person that made the subscription purchase. Use CURRENT_USER constant to retrieve only subscriptions for the current logged in user.

member_id="123"

member_id="CURRENT_USER"

`limit`

Number of results to return

limit="10"

Variables

`id`

The unique id of the vault in the CartThrob system

`order_id`

Order that initially spawned the subscription

`vault_id`

vault or token id (if item is a vault/token)

`member_id`

ID of the member that authorized this vault

`start_date`

when the subscription began

{start_date format="Y-m-d"}

`end_date`

when the subscription ends, if applicable

{end_date format="Y-m-d"}

`total_occurrences`

`used_total_occurrences`

`trial_occurrences`

`used_trial_occurrences`

`interval_length`

`interval_units`

`allow_modification`

`price`

`trial_price`

`status`

`last_paid_amount_numeric`

`last_paid_amount`

`is_delinquent`

`refund_amount`

`price_per_day`

`refund_amount_numeric`

`delinquent_amount`

`delinquent_amount_numeric`

`next_billing_date`

`days_to_next_billing`

`is_trial`

`can_renew`

`is_cancelled`

`occurences_used_up`

`vault_gateway`

Example

{exp:cartthrob:subscriptions limit="10" member_id="{member_id}"}
    {id}
    {status}
    {description}
    {gateway}
    {member_id}
    {vault_id}
    {last_bill_date format="%Y-%m-%d"} this will output todays date if not set
    {if start_date}{start_date format="%Y-%m-%d"}{/if} this will output todays date if not set
    {if start_date}{end_date format="%Y-%m-%d"}{/if}  this will output todays date if not set
    {total_occurrences}
    {total_intervals}
    {interval_units}
    {allow_modification}
    {price}
    {trial_price}
    {order_id}
    {error_message}
{/exp:cartthrob:subscriptions}

`vaults`

Outputs data about existing vaults.

Parameters

`id`

Vault id

id="123"

`order_id`

The order id that was initially used to generate the vault.

order_id="123"

`member_id`

Member id of the person that made the subscription purchase. Use CURRENT_USER constant to retrieve only vaults for the current logged in user

member_id="123"

`limit`

Number of results to return

limit="10"

Variables

`id`

The unique id of the vault in the CartThrob system

`order_id`

ID of the order used to generate the vault

`token`

The vault's private token

`gateway`

Gateway used to create the vault

`member_id`

ID of the member that authorized this vault

Example

{exp:cartthrob:vaults limit="10" member_id="{member_id}"}
    {id}
    {token}
    {gateway}
    {member_id}
    {order_id}
{/exp:cartthrob:vaults}

`vaults`

Outputs data about existing vaults.

Parameters

`id`

Vault id

id="123"

`order_id`

The order id that was initially used to generate the vault.

order_id="123"

`member_id`

Member id of the person that made the subscription purchase

member_id="123"

`limit`

Number of results to return

limit="10"

Variables

`id`

The unique id of the vault in the CartThrob system

`order_id`

ID of the order used to generate the vault

`token`

The vault's private token

`gateway`

Gateway used to create the vault

`member_id`

ID of the member that authorized this vault

Example

{exp:cartthrob:vaults limit="10" member_id="{member_id}"}
    {id}
    {token}
    {gateway}
    {member_id}
    {order_id}
{/exp:cartthrob:vaults}

`permissions`

Outputs data about permissions assigned to members.

NOTE Do not confuse this tag with permission_items. See CartThrob Permissions Admin module for more information.

Parameters

`id`

Vault id (not subscription id)

id="123"

`sub_id`

Subscription id associated with permission (if any)

sub_id="123"

`member_id`

Member id of the person that made the subscription purchase

member_id="123"

`order_id`

Order ID associated with the permission (if any)

order_id="123"

`item_id`

Item ID associated with the permission (if any)

item_id="123"

`limit`

Number of results to return

limit="10"

Variables

`id`

The unique id of the vault in the CartThrob system

`permission`

The permission ID

`member_id`

ID of the member that authorized this vault

`sub_id`

subscription id (it item is not a subscription this will be blank)

`item_id`

item id associated with this permission

`order_id`

Order that initially spawned the subscription

Example

{exp:cartthrob:permissions limit="10" member_id="{member_id}"}
    {id}
    {member_id}
    {sub_id}
    {item_id}
    {order_id}
{/exp:cartthrob:permissions}

`has_permission`

Used to protect data from users that don't have the proper permissions.

Parameters

`permissions`

permissions="123"

`member_id`

Member id of the customer who's access you need to check

member_id="123"

Conditionals

`{if no_results}`

Outputs alternate content if the user doesn't have permissions to access the content

Example

{exp:cartthrob:has_permission permissions="123" member_id="{member_id}"}
    Some content!

    {if no_results}
        You don't have access to this
    {/if}
{/exp:cartthrob:has_permission}

`update_subscription_details`

This generates a form to update an existing subscription.

Parameters

This tag includes the following parameters for updating existing subscriptions

`sub_id`

The subscription id that needs to be updated. This is required. If not included, you will receive an error.

`subscription_name`

The name of the subscription

`subscription_description`

The description of the subscription

Variables

`{if no_results}`

If you specify a sub_id parameter for a nonexistent subscription, the contents of the no_results tag will be output inside this form.

{if no_results}A valid subscription ID was not specified. Please select a valid subscription to update.{/if}

Example

{exp:cartthrob:subscriptions}
    {if allow_modification}
        {exp:cartthrob:update_subscription_details}
            <input type="text" name="subscription_name" value="{name}">

            {exp:cartthrob:subscription_select name="subscription_interval_units" options="days|months" selected="{interval_units}" }
            {!-- see subscription_select tag below for more details on encrypting  customer selectable options --}

        {/exp:cartthrob:update_subscription_details}
    {/if}
{/exp:cartthrob:subscriptions}

`update_subscription_form`

This tag works in the same way that CartThrob's checkout_form works, but is intended only for updating existing subscriptions, and not for purchasing new subscriptions. If you add items to the cart before submitting this form, they will be removed from the cart.

In addition to updating payment information, you can also update details about the subscription itself. All of the parameters used in the update_subscription_details tag can be used with this tag.

If you specify a subscription_plan_id all other parameters related to the subscription details will be overridden by those of the subscription plan

Parameters

In addition to all of the standard checkout_form parameters, there is one additional parameter: sub_id.

`sub_id`

This is the id of the subscription that you'd like the customer to be able to update. This parameter is required and if not found or invalid, an error will be output.

sub_id="123"

**Note** The `sub_id` is a required parameter for this tag. If the sub_id parameter is not set, this form will report an error.

Example

{exp:cartthrob:subscriptions }
{if allow_modification}
    {exp:cartthrob:update_subscription_form sub_id="{id}"}

        You are about to update subscription #{id} for order #{order_id}
        {gateway_fields}

        <input type="submit" name="Submit" /> 
    {/exp:cartthrob:update_subscription_form}
{/if}
{/exp:cartthrob:subscriptions}

`plans`

The plans tag outputs data related to available global subscriptin plans.

Parameters

`limit`

The number of plans to display

Variables

`id`

Plan ID

`status`

This will output the current status of this subscription plan

`name`

The descriptive name of the plan

`description`

A description of the plan

`total_occurrences`

The total number of occurrences that will be billed with this plan

`trial_occurrences`

The total number of times the trial price should be billed switching to the standard price.

`interval_length`

This is the rebill periodicity. Generally this will be 1 (for once a month). By default it will be 1.

`interval_units`

This is the rebill period. Acceptable values are years, months, weeks, days. Defaults to "months" if not set.

`allow_modification`

whether or not the customer shoud be allowed to update their subscription

`price`

The formatted amount of the subscription plan

`trial_price`

The formatted trial price of the subscription

`price_numeric`

The amount of the subscription

`trial_price_numeric`

The trial price of the subscription

Example

{exp:cartthrob:plans}
    {id}
    {name}
    {description}
    {total_occurrences}
    {allow_modification}
    {interval_units}
    {interval_length}
    {trial_occurrences}
    {total_occurrences}
{/exp:cartthrob:plans}

`subscription_select`

This tag will allow you to output encrypted subscription options so that your customers can make selections, without being able to modify the available choices.

Parameters

`name`

This is the name of the dropdown select that will be created. Any one of the following can be used as the name for your select. These are the only selectable options

subscription_interval_units
subscription_interval_length
subscription_start_date
subscription_end_date
subscription_status
subscription_name (this can also just be passed as plain text)
subscription_description (this can also just be passed as plain text)

`default`

If no selection has been set yet, a default value can be set. If there is a value in selected that value will supersede this one.

default="months"

`selected`

The option value that you would like selected

selected="{interval_units}"

`add_blank`

This will add a blank option

add_blank="yes"

`id`

CSS Id

`class`

CSS class

`extra`

Add any extra content you'd like to your select dropdown

extra=" rel='my_option' "

`options`

pipe delimited list of options that you would like encrypted.

options="days|weeks|months|years"

you can also add a display name to the option by adding a : with descriptive text for each option. For instance, December 10, 2012 is a lot more legible than the timestamp: 1355133947 of the same day.

options=" 1355133947: Today | 1355233947: Tommorrow "

You can use the following values with the respective dropdowns

subscription_interval_units (days, months, weeks, or years)
subscription_interval_length (numeric)
subscription_start_date (must be a PHP timestamp)
subscription_end_date (must be a PHP timestamp)
subscription_status (open or closed)

Example

{exp:cartthrob:subscription_select name="subscription_interval_units" options="days|months" selected="{interval_units}" }

Changelog

Version 4.3.1

Released March 17, 2022

FIXED: Rebill Command breaks list parameter on eecli.php requests #65 FIXED: Edit Subscription Form has End Date value as Start Date #63 FIXED: Uninstaller generates DB errors if cartthrob_notifications is not present #61

Version 4.3.0

Released February 10, 2021

ADDED: 'is_cancelled', 'occurences_used_up', and 'is_trial' as tags to the 'subscriptions' template tag
ADDED: Asterisk as visual cue on renewability of a subscription within the Control Panel
ADDED: Rebill Cli Command (#32)
UPDATED: Control Panel views to use database pagination (#27)
UPDATED: Improves performance of internal option methods (#27)
UPDATED: Cancel Subscription logic to keep subs open to period end if funds aren't involved in cancellation (#44)
FIXED: issue with Total Occurrences not being respected for certain situations
FIXED: Various bugs with MySQL and the strict setting (#46)

Version 4.2.0

Released December 14, 2021

FIXED: Missing cancel_sub template in template installer. #31
FIXED: Updating Plan with no Permissions. #39

Version 4.1.0

Released June 1, 2021

ADDED: ExpressionEngine 6 support.
UPDATED: Replaces cartthrob_addon_register with cartthrob_boot hook in extensions table.

Version 4.0.1

Released April 26, 2021

FIXED: Warning disabled by invalid data type on permission getter.
FIXED: Exception thrown during update due to reference to deprecated mbr_addon_builder. Removed reliance on mbr_addon_builder.

Version 4.0.0

Released April 17, 2021

ADDED: CartThrob 5.5 Support.
ADDED: ExpressionEngine 5 Support.
ADDED: Authorize.net support as a billing option.
ADDED: Manual rebill functionality.
ADDED: Ad hoc billing capabilities.
UPDATED: Moved CodeIgniter models to ExpressionEngine Model objects.
UPDATED: Moved CodeIgniter libraries to ExpressionEngine Services.
UPDATED: Installation template formatting and removes legacy ExpressionEngine tags.

Version 2.5

Released January 23, 2014

Major fixes & enhancements throughout subscriptions & permissions especially concerned with template tags and backend administration.

ADDED: full set of templates to be used as examples for creating subscription sales sites.
ADDED: ability to set a permission on a subs plan
ADDED: ability to set more subscription options when adding an item to a cart.
ADDED: bettor error reporting in subs manager to make it more obvious when something has failed.
ADDED: members with vaults method to vault model
ADDED: method to permissions model to get permissions related to a specific sub_id
ADDED: method to permissions tag where you can pass a sub_id to check for active permissions. If the sub_id is closed, the permissions will not be assigned
ADDED: method to subscriptions field type to pull permissions that have been set in permissions manager
ADDED: method to subscriptions to find any vault data even if the token is missing so that we start with something, rather than having nothing to go on if something goes wrong with a transaction.
ADDED: method to update / close permissions if the related subscription is expired.
ADDED: method to use status and other db fields in subscription model to get_subscriptions. Now you can use status='open' or status='open|pending' as a parameter in the subscriptions tag to get information about subscriptions
ADDED: pending subscriptions view to subscriptions manager.
ADDED: method to see when next bill is expected for a certain sub.
FIXED: an issue with sequential order numbers in subscriptions
FIXED: clean_sub_data method in module no longer sets bad data if a specific key is not passed in. This allows sending of partial data sets without overwriting existing data that is not being updated
FIXED: issue where permissions were assigned twice when purchasing subscription products.
FIXED: issue with subscriptions field type where if you'd set it as the price field you'd get crazy prices back. Now it just gets the price of the sub as you might expect.
FIXED: issue with subscriptions model where arrays were not being serialized. This primarily affected permissions being saved correctly.
FIXED: issues in module where permissions were not being serialized and unserialized correctly, causing permissions added to a subscription to either be ignored, or only the first permission set to be used.
FIXED: issues with adding a plan to the cart where plan data was either being ignored or added incorrectly.
FIXED: issues with deleting subscription items from the backend.
FIXED: Many small issues and inconsistencies with Permissions and Subscriptions
FIXED: various fixes to subs and perms field types to get around incompatibility with GRID field type

All previous changes are listed in CartThrob's changelog

Subscriptions Version 4.3.1

About CartThrob Subscriptions

How CartThrob Subscriptions Works

Features

Installation

Requirements

Installing the Addon

Upgrading

Sample Templates

Settings

Notifications

Notification Variables

Setting up rebilling

Rebill Command

Systemd Config File

Legacy extload Method (deprecated)

Setting up the FieldType

General User Flow

Key Concepts

Subscription System

Token Vaults System

Permissions System

Administration

Administering Plans

Administering Subscriptions

Administering Subscribers

Tags

Add to cart form and checkout form parameters

subscription_plan_id

subscription

subscription_allow_modification

subscription_interval_units

subscription_interval_length

subscription_start_date

subscription_end_date

subscription_price

subscription_total_occurrences

subscription_trial_price

subscription_trial_occurrences

subscription_name

permissions

options:[your_parameter_name]

update_cart_form

Parameters

subscription

subscriptions

Parameters

id

order_id

member_id

limit

Variables

id

order_id

vault_id

member_id

start_date

end_date

total_occurrences

used_total_occurrences

trial_occurrences

used_trial_occurrences

interval_length

interval_units

allow_modification

price

trial_price

status

last_paid_amount_numeric

last_paid_amount

is_delinquent

refund_amount

price_per_day

refund_amount_numeric

delinquent_amount

delinquent_amount_numeric

next_billing_date

days_to_next_billing

is_trial

can_renew

Legacy `extload` Method (deprecated)

`subscription_plan_id`

`subscription`

`subscription_allow_modification`

`subscription_interval_units`

`subscription_interval_length`

`subscription_start_date`

`subscription_end_date`

`subscription_price`

`subscription_total_occurrences`

`subscription_trial_price`

`subscription_trial_occurrences`

`subscription_name`

`permissions`

`options:[your_parameter_name]`

`update_cart_form`

`subscription`

`subscriptions`

`id`

`order_id`

`member_id`

`limit`

`id`

`order_id`

`vault_id`

`member_id`

`start_date`

`end_date`

`total_occurrences`

`used_total_occurrences`

`trial_occurrences`

`used_trial_occurrences`

`interval_length`

`interval_units`

`allow_modification`

`price`

`trial_price`

`status`

`last_paid_amount_numeric`

`last_paid_amount`

`is_delinquent`

`refund_amount`

`price_per_day`

`refund_amount_numeric`

`delinquent_amount`

`delinquent_amount_numeric`

`next_billing_date`

`days_to_next_billing`

`is_trial`

`can_renew`

`is_cancelled`

`occurences_used_up`

`vault_gateway`

`vaults`

`id`

`order_id`

`member_id`

`limit`

`id`

`order_id`

`token`

`gateway`

`member_id`

`vaults`

`id`

`order_id`

`member_id`

`limit`

`id`

`order_id`

`token`

`gateway`

`member_id`

`permissions`

`id`

`sub_id`

`member_id`

`order_id`

`item_id`

`limit`