CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Sell Your First Subscription

This walkthrough takes a working CartThrob store to a first recurring sale. You will:

  • create a monthly membership Plan;
  • buy it as a test customer;
  • confirm that the customer can see members-only content;
  • run a renewal.

Use a development site and your gateway’s sandbox or test mode throughout.

Before you start

  • CartThrob 10.0.1 or newer, with its store templates installed. The Subscriptions example templates reuse the store template group’s header, navigation and checkout pages. See Templates overview.
  • ExpressionEngine 6.1 or newer and PHP 8.0 or newer.
  • A payment gateway that supports subscriptions, configured in sandbox/test mode: Stripe Payments, classic Stripe, or Authorize.net with CIM enabled. Other gateways are rejected for subscription checkouts. See Eligible payment gateways.
  • A test member account that can log in on the front end.
  • Command-line access to run ExpressionEngine’s eecli.php. Renewals are run by a command, not by page visits.

1. Install both add-ons

The Subscriptions package contains two add-on folders: cartthrob_subscriptions and cartthrob_permissions_manager.

  1. Copy both folders into system/user/addons/.
  2. In the Control Panel, go to Add-ons.
  3. Install CartThrob Permissions Manager.
  4. Install CartThrob Subscriptions.

If Permissions Manager is not installed, opening Subscriptions returns you to the Add-ons page.

2. Turn on Purchased Items

Subscriptions uses CartThrob’s Purchased Items records to find what a customer last paid. That amount is used to calculate cancellation refunds and Plan-change credits. Without Purchased Items, those amounts are always zero and no refund is issued.

In CartThrob > Purchased Items (reference):

  1. Set Save each purchased item to its own channel entry? to Yes.
  2. Select the Purchased Items Channel.
  3. Map the Purchased Items fields, including Purchased Items Sub ID Field Name, Purchased Items Price Field Name and Purchased Items Order ID Field Name.

Until this is configured, the Subscriptions Control Panel shows the warning “You haven’t configured Purchased Items for use by CartThrob. This will prevent refunds from being applied.”

Then, in CartThrob > Orders under Order Data Fields, check that Total and Payment Gateway are mapped (refunds need both), and map Subscription ID. Nothing is mapped to Subscription ID on a new install; the sample Orders channel’s field is Payment: Subscription ID.

Expected result: the warning no longer appears on Add-ons > CartThrob Subscriptions. For every field Subscriptions uses, and what happens without it, see CartThrob field mappings.

3. Create a permission for the members area

  1. Go to Add-ons > CartThrob Permissions Manager > Permissions.
  2. Create a permission named Members Area.
  3. Note its ID. You will use it in the template in step 6.

4. Create a Plan

  1. Go to Add-ons > CartThrob Subscriptions > Plans and select New.
  2. Enter these values:
Field Value
Name Monthly Membership
Price 10.00
Interval Length 1
Interval Unit months
Total Occurrences leave blank (renews until cancelled)
Permissions Members Area
  1. Leave Allow customer to modify subscription? enabled. It lets the customer switch to another Plan later.
  2. Select Save.

The Plan supplies terms for new purchases. Each Subscription keeps its own copy of the terms it was bought with, so editing the Plan later does not change existing customers’ prices or schedules. See Plans, Subscriptions and stored terms.

5. Install the example templates

  1. Go to Add-ons > CartThrob Subscriptions > Utilities > Installation.
  2. Select the subscriptions template group.
  3. Leave the optional sample channel unselected for this walkthrough.
  4. Install.

The subscriptions/index template lists your Open Plans. Each Plan has an Add plan button built with add_to_cart_form and subscription_plan_id="{id}".

If a subscriptions template group already exists, the Installation page does not offer it again and never overwrites it.

Installing also creates a Subscriptions demo members Permission and a subscriptions/members page that checks for it. This walkthrough uses its own Members Area Permission and template in the next step. To try the bundled members page as well, add the demo Permission to your Plan’s Permissions before buying.

6. Protect some content

Create a template, for example members/index. Use your permission ID from step 3:

{exp:cartthrob:has_subscription_permission permissions="7" member_id="CURRENT_USER"}
    <h1>Welcome to the members area</h1>

    {if no_results}
        <p>This area is for members. <a href="{path='subscriptions'}">Join now</a>.</p>
    {/if}
{/exp:cartthrob:has_subscription_permission}

Visit it while logged in as your test member. You should see the “Join now” message.

Use the Subscription-aware tag for subscription content:

Tag What it checks When to use it
has_permission Does the member have an assignment for this Permission? It does not check whether a linked Subscription is active, expired or refunded. Access controlled by the assignment itself, such as a one-time purchase or a manual grant. It never expires on its own.
has_subscription_permission Does the member have this Permission through a Subscription that still qualifies? Subscription status, End Date and cancellation refunds all count, as well as the assignment. Content that should be available only while the member’s subscription entitlement lasts, including the paid time remaining after a cancellation.

Access through has_permission doesn’t end when the subscription ends, because the assignment stays in place. See Which permission tag should I use?

7. Buy the Plan

  1. Log in as your test member and visit /subscriptions.
  2. Select Add plan under Monthly Membership, then check out using a sandbox test card.

Expected result:

  • The checkout result page reports a successful payment.
  • Add-ons > CartThrob Subscriptions > Subscriptions lists a new Open Subscription for the member, on the Monthly Membership Plan.
  • Open the Subscription. Its Next Billing Date is one month after the purchase.
  • The members/index template now shows the members-area content.

If checkout rejects the gateway, the selected gateway cannot save cards for renewal. Use one of the gateways listed in Before you start.

8. Run a renewal

On a test Subscription, you can bring the renewal forward instead of waiting a month:

  1. Edit the Subscription and set Next Billing Date to today.
  2. Save it.

Changing this date also resets the calendar day future renewals fall on. Only do this on test Subscriptions.

Then, from the site’s root directory, run:

php system/ee/eecli.php cartthrob:subscriptions:rebill

The exact command for your installation is shown under Rebill Configuration on Subscriptions > Settings.

Expected result:

  • A renewal Order is created and charged to the saved sandbox card.
  • The Subscription stays Open.
  • Its Last Bill Date is today.
  • Its Next Billing Date moves forward one month.

9. Schedule renewals

Renewals only happen when the rebill command runs. Schedule it before you take real orders, typically once a day with cron. See Setting up rebilling for scheduling, retries and failed payments.

Next steps