CartThrob Subscriptions Version 2.61

CartThrob Subscriptions gives your CartThrob powered website the ability to take recurrent payments, for things like membership, layway, and monthly donations. CartThrob Subscriptions is an addon for CartThrob. 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.

CartThrob Subscriptions addon contains robust abilities to generate and maintain recurrent bills (subscriptions) for customers, maintain customer permissions, and customer data token vaults.

There are three key parts of CartThrob Subscriptions

  1. Recurrent Billing
  2. Vault/Tokens
  3. Permissions system

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. read more

A secondary feature is the data vault / token based billing portion. CartThrob uses your gateway to store sensitive data, offloading the responsibility & liability onto the gateway provider. CartThrob uses the customer token to initiate a charge on a time basis that you specify. Additionally, a future feature of CartThrob will allow you to arbitrarily add additional customer fees if you have a token for their account available. read more

Permissions is the third 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. This will allow you to selectively show content to a user based on previous purchases. read more

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.

Features

  • Take subscription payments in addition to product & donation payments

  • Create and manage global subscription plans

  • Create dynamic subscription plans

  • Simple setup

  • Email notifications for purchase, rebill success, hold and failure events

  • Create and sell permissions (ACL-access control levels)

  • Customers can update their own subscriptions

  • Works with many popular payment gateways including Stripe, Authorize.net and eWay

  • Uses token/vault based payments. No credit card data is stored on your site.

Requirements

  • ExpressionEngine 2.8+
  • CartThrob 2.61+
  • PHP 5.3+

Installation

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

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

  1. Configure notifications through CartThrob's notification settings (addons » modules » cartthrob » notifications)
  2. 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 insructions below

Upgrading

  • Upload the /system/expressionengine/third_party/cartthrob_subscriptions/ folder to /system/expressionengine/third_party/ Overwriting existing files.
  • Go to EE settings » addons » and click "Run Module Updates"

Settings

By adding CartThrob Subscriptions, you will notice

  1. It adds a new module with ability to review and edit customer subscriptions.
  2. It adds a new setting to the CartThrob settings panel.
  3. It adds new notifications to CartThrob's notifications panel.
  4. It adds a new subscriptions fieldtype to EE's addons » fieldtypes fields

Each of these settings is covered in detail in this documentation. Each offers important new functionality.

How it works

CartThrob Subscriptions utilizes the token based billing functions of your chosen gateway. Many payment gateways offer a multitude of payment services, including two services that are useful for recurrent billing. Gateways generally offer token payments also sometimes known as vault payments, and they generally offer recurrent billing services, which CartThrob does not use.

Recurrent billing services are managed wholly by the gateway. These services are not used by CartThrob Subscriptions. Recurrent billing services offload all respsonsibility for billing to the gateway company. The benefit of this is that they're generally very easy to set up quickly. The downside is that you lose most or all control to the gateway. Using their services, you are limited in the schedules you can create, how often you can rebill, and the number of recurrent bills you can set per customer (in some cases.) One of the major drawbacks of this method is that deep integration and feedback from the gateway is often difficult or impossible. For instance, using this method, some gateways may not notify your site if a credit card has been declined and expires, making it difficult to restrict access to people who aren't paying.

Token billing is a service provided by the gateway where all customer billing and credit card information is stored by the gateway. CartThrob utilizes this service. This allows us to safely store all customer information with the gateway company, offloading responsibility for storage of sensitive data. All of the rest of the subscription details are stored and managed on your site. This means that you have direct control of all subscription details, and those same subscription details are consistent across all gateways. CartThrob is provided a token by the gateway company for the customer, and CartThrob uses this token to make charges as needed against the customer's credit card at prescheduled or arbitrary times as needed.

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_update_success Sent when a customer has successfully updated their subscription details
  • 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:

id

This is the subscription id. Most of the time this will only be useful when combined with the subscriptions tag.

member_id

This is the ID of the member that purchased the subscription

order_id

This is the entry id of the order that was originally used during the creation of this subscription

vault_id

ID of the vault that stores the token for the rebilling of this transaction. Most of the time this will only be useful when combined with the vaults tag.

start_date

This is a PHP timestamp of the planned start date for this subscription. You can format it according to standard EE date variable formatting

{start_date format="%D, %F %d, %Y - %g:%i:%s"}

modified

This is a PHP timestamp of the last time this subscription was modified. You can format it according to standard EE date variable formatting

{modified format="%D, %F %d, %Y - %g:%i:%s"}

last_bill_date

This is a PHP timestamp of the last time this subscription was successfully billed. You can format it according to standard EE date variable formatting

{last_bill_date format="%D, %F %d, %Y - %g:%i:%s"}

end_date

This is a PHP timestamp of when the subscription is scheduled to end. You can format it according to standard EE date variable formatting

{last_bill_date format="%D, %F %d, %Y - %g:%i:%s"}

status

This is the current status of this subscription. Possible values are open, closed, pending, hold. When subscriptions are running successfully they will use the open status. When they've had a rebill error, they will initially be on "hold", and when they reach their max rebill dates, they will eventually be set to "closed". "Pending" status is reserved for subscriptions that are currently in the process of being renewed, but with open payment transactions.

name

This is the descriptive name / title of this addon

description

This is the description of this subscription.

total_occurrences

This is the number of time this item should rebilled. If blank, then it's unlimited

used_total_occurrences

This is the number of time this item has been successfully rebilled.

interval_length

This is the interval between rebillings. If the interval unit is months, and this is set to 6, the rebill would occur every 6 months. 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.

trial_occurrences

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

allow_modification

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

price

The amount of the subscription

trial_price

The trial price of the subscription

error_message

An error message (if any) related to this rebill attempt

plan_id

The subscription plan_id (if any) used on this transaction

rebill_attempts

The number of times the system has tried unsuccessfuly to rebill.

Setting up rebilling

Rebilling requires that your system be told to periodically check for expired and expiring subscriptions. You can either manually process your subscriptions (there's a point and click button in the settings for this), or ideally you should automate the process by using CRON. CRON is a time based scheduling application already available on most hosting platforms. CRON will initiate CartThrob to periodically check for subscriptions that need to be rebilled. Setup of CRON is simple, and CartThrob's settings outputs the specific CRON command needed to process subscriptions on a daily basis. Most hosts provide an administrative interface for CRON, or you can generally provide our CRON command to the host's support and they will add it for you. Once cron is set up once, you need take no further action with it in the future.

Note Rebilling is initiated by your site, and not the payment gateway. You must either use CRON to automate these rebilling pings, or you must click the manual process button to process payments that need to be rebilled.

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.

NOTE: Our CRON methods make use of a file called extload.php in themes/third_party/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.

  1. If you can execute shell scripts on your server:

    /your/server/path/to/themes/third_party/cartthrob/lib/cron_subscriptions.sh /server/path/themes/third_party/cartthrob/lib/extload.php

  2. If you can run perl scripts on your server:

    /your/server/path/to/themes/third_party/cartthrob/lib/cron_subscriptions.pl /server/path/themes/third_party/cartthrob/lib/extload.php

  3. If your server allows the use of PHP's "passthru" function: /your/server/path/to/themes/third_party/cartthrob/lib/extload.php cron process_subscriptions

  4. You can also manually call your rebill URL manually. (the URL is listed in your settings page)

  5. 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

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

Once the fieldtype is instlled, 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.

Suggested user flow

  1. 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.

  2. 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)

  3. The initial subscription costs are billed immediately, and the subscription details are stored in CartThrob for future rebill attempts.

  4. Permissions related to the subscription are stored

  5. Customer transaction is complete

  6. Customer is notified that they've made a successful transactions via email

**In future rebill attempts: **

  1. 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.

  2. If an item needs rebilling, CartThrob will initiate a new order and attempt to complete the transaction using the Token provided by your gateway and stored in your database. If the transaction is successful, the order will be updated. If not, CartThrob will put the subscription on hold and attempt to rebill the subcription until it is successful, or until the subscription is cancelled by the gateway.

  3. 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.

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:

  1. Parameters to create subscriptions on the fly
  2. A custom subscriptions fieldtype that allows you to easily create subscriptions on a per-product basis
  3. 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. Currently, CartThrob supports the following gateways:

  • Authorize.net (CIM)
  • eWay (Token Payments)
  • Payleap (SCM)
  • Sage (Token)
  • 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" of one or more types to each item purchased. 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 affect on EE's backend access or other member group options.

Administration

Administering subscriptions

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

Create a subscription plan Create a subscription plan.

View existing subscriptions Viewing existing subscriptions

Creating a new charge for an existing customer Creating a new charge for an existing customer

Administering permissions

CartThrob subscriptions module also includes the CartThrob Permissions Admin module for creating permission items, and editing permissions that have been assigned to customers.

Tags

Several new tags are available for use with CartThrob Subscriptions, and several existing tags have new parameters.

CartThrob Subscriptions adds several parameters to the following CartThrob tags:

CartThrob Subscriptions also adds the following new tags:


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 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 -1 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

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 subscription 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

plan_image

Thumbnail image for plan

description

A description of the plan

long_description

This is a more detailed description of this subscription plan, which may include HTML and uses ExpressionEngine's Rich Text Editor.

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)
  • subscription_plan_id
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)
  • subscription_plan_id (the id number of your subscription plan)
Example
{exp:cartthrob:subscription_select name="subscription_interval_units" options="days|months" selected="{interval_units}" }

Changelog

Version 2.61

Release October 6, 2014

  • ADDED: Ability to change subscription plans using update_subscription_details
  • ADDED: subscription_plan_id as a valid name for subscription_select
  • ADDED: plan_image / support for file uploads in subscriptions plan creation.
  • ADDED: long_description / support for Rich Text Editor in description during subscriptions plan creation
  • FIXED: Various issues involving permissions when editing a subscription or subscription plan.
  • ADDED: next_billing_date variable to subscriptions tag.

Version 2.6

Released June 24, 2014

  • ADDED: has_subscription_permission tag.
  • ADDED: method to subs model to get_subscriptions_without_vaults
  • CHANGED: customer name now comes from the screen name rather than a saved last name stored in an order. This makes it possible to "import" subs that do not have a related order.
  • CHANGED: made the system to get subscriptions much more flexible. It can now be passed a table prefix so that it can be used within complex joins with other tables.
  • FIXED: A string to array conversion bug in the permissions manager fieldtype
  • FIXED: Added cartthrob path in permission item model to fix unable to load model errors.
  • FIXED: issue in subscription model where too many pending items would be returned. This issue never made it into public releases
  • FIXED: issue where a new vault ID was generated for an existing subscription but was not added to the subscription during a subscription update.
  • FIXED: issue where ALL subscriptions could never be listed if no member id was specified. This is bad if you you are an admin wanting to view all subs in a template. We added the ability to list all for super admins (only supers at present)
  • FIXED: issue where an item end date was reached, subscription was not being held.
  • FIXED: issue with EXTLOAD where some systems using CRON could not use it because they were not telling the system they were running CLI commands. I added extra checks for systems (like PHP CGI) to identify whether ext load was being hit with an HTTP connection or a command line action.
  • FIXED: issue with get_pending_subscriptions where like-named vault values would override subscription values.
  • FIXED: issues where plan data was overriding subs data in the subscriptions tag if the sub was based on a plan
  • FIXED: several issues with payments lib where an item could be considered "processing" when it had in fact "failed" during a token generation operation
  • FIXED: some issues where a new subscription would be created if a subscription ID couldn't be found because it had been overwritten by a plan ID (also fixed the plan ID overriding the sub id)
  • FIXED: subs issue where any sub with a total occurrence of 0 (unlimited) would be put on hold.
  • FIXED: subs model. When a subscription is closed it sets the end date according to the last bill date + interval so that their subscription closes when it should rather than immediately upon cancellation
  • FIXED: subscriptions issue where entries with 0 set for total occurrences were never being set as a pending subscription
  • FIXED: subscriptions issue where start date was always being set to 1970
  • UPDATED: made it possible to add a subscription to the subscriptions table without a vault. The user can't be charged without a vault token, but at least there's an opportunity to then contact the customer to get them to update their billing details.

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