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

Understanding the Example Templates

Subscriptions ships with a working example store: a subscriptions template group of 14 templates. This page walks through it in the order a customer moves through it, from choosing a subscription to managing it in their account. It explains what each template demonstrates, which tags do the work, and what you can safely change.

Use it alongside the tag reference. The excerpts below are trimmed; open the installed templates to see them whole.

Installing the examples

Install them from Add-ons > CartThrob Subscriptions > Utilities > Installation. See Installation.

  • The examples need CartThrob’s store templates. They embed the store group’s header, navigation and footer, and link to its product, invoice and checkout pages.
  • Plans are not created for you. Create at least one Open Plan in Subscriptions > Plans before you visit /subscriptions.
  • The optional channel adds a “Store - Subscriptions” channel with a Monthly Donation sample product for subscription_products.
  • A demo Permission is created for you. Installing creates a Subscriptions demo members (site 1) Permission, using your site ID, and wires it into the members page and the sample product. Assign it to any Plan you create if buying that Plan should open the members page.

Upgrading: installing never overwrites an existing subscriptions group. If you already have one, compare it with the files in the add-on’s installer/templates/subscriptions.group folder. See Upgrading.

Map of the templates

Stage Template Demonstrates
Navigation _nav Links shared by every page. A Cart link appears only when the cart has a subscription (cart_has_subscription).
Choose index (also embedded by subscription_plans) Selling Plans.
Choose subscription_products Selling a channel product that has a Subscription Settings field.
Choose subscription_custom A donation: the customer chooses the amount and schedule.
Cart view_cart Changing subscription terms in the cart.
Checkout checkout Checkout for a cart containing subscriptions, plus an advanced “pay over time” option.
Checkout save_card_checkout Saving a card at checkout without a subscription.
Result order_info The checkout result and invoice link.
Account account The customer’s subscriptions and payment history, with links to manage each one.
Manage update_subscription Replacing the card a subscription is billed to.
Manage change_plan Moving to another Plan.
Manage cancel_sub Cancelling.
Protect members Content shown only to a customer whose subscription grants the demo Permission.

A customer’s path through the store is:

  1. Choose a subscription on index, subscription_products or subscription_custom.
  2. Review it on view_cart.
  3. Pay on checkout.
  4. See the result on order_info.
  5. Manage it from account, which links to update_subscription, change_plan and cancel_sub. Each returns to account when it is done.
  6. Open members to see the content their subscription unlocks.

The three management pages take the Subscription ID from the URL, as in subscriptions/change_plan/123. Each one reads it as {segment_3}.

Try the demo

Run through the demo once as a customer before you change anything. Use a development site, a test member account and a test gateway. On a test store, Offline Payments lets you check out without a provider.

  1. Install both options on Utilities > Installation. You get the templates, the sample Monthly Donation product and the demo Permission.
  2. Log in as your test member at /subscriptions/members. It says your account does not currently have access.
  3. Buy the product. On /subscriptions/subscription_products, select Subscribe now!. The cart shows Monthly Donation at its 5.00 trial price. Select Proceed to Checkout, fill in the billing details and select Complete Checkout. order_info reports “Payment successful”.
  4. Check access. /subscriptions/members now shows the members content, because the product grants the demo Permission.
  5. Check the account. /subscriptions/account lists the subscription with its payment, and links to change the card, change Plan or cancel.
  6. Change Plan on change_plan. The page shows your unused balance, which is applied to the new Plan. The old subscription is closed and a new one starts on the Plan. Access now follows the new Plan’s Permissions, so members closes again unless that Plan grants the demo Permission.
  7. Cancel on cancel_sub. account shows “Not renewing — access until” the end of the period already paid for.

You can also add a Plan from index and a donation from subscription_custom and check them out together. Each becomes its own subscription, and both use the card saved at that checkout.

1. Choosing a subscription

The examples show three ways to sell a subscription. Pick the one that matches how your terms are set.

Way Terms come from Use when
Plan (index) A Plan in the Control Panel. You sell a few fixed memberships and want to manage them in the Control Panel.
Product (subscription_products) A Subscription Settings field on a channel entry. The subscription is a product in your catalog, possibly with physical goods.
On the fly (subscription_custom) The form, with optional customer choices. Donations or “build your own” terms.

Plans: index

plans lists Open Plans. An add_to_cart_form adds the chosen one by ID:

{exp:cartthrob:plans limit="10"}
    <h4>{name}</h4>
    <p>You will be billed every {interval_length} {interval_units} at {price}.</p>
    {if member_has_plan == "1"}<p>You already have this Plan.</p>{/if}

    {exp:cartthrob:add_to_cart_form subscription_plan_id="{id}" return="subscriptions/view_cart"}
        <button type="submit">Add plan</button>
    {/exp:cartthrob:add_to_cart_form}
{/exp:cartthrob:plans}

The Plan’s price, schedule, trial and permissions come from the Control Panel. The form needs no product entry_id. The example also shows each Plan’s ID in brackets as a development aid; remove it on a real site.

Products: subscription_products

channel:entries lists the subscriptions channel. The {subscription_details} field pair outputs each product’s terms, and a normal add_to_cart_form with the entry’s entry_id adds it. Products keep normal shipping and tax rules, because a subscription product can include physical goods.

A product’s trial price applies to the first payment only. The sample Monthly Donation charges 5.00 at checkout, then 12.00 a month. See Subscription Settings Fieldtype.

Shipping and tax in the demo: Plan and product rows are charged your store’s normal shipping and tax. Only the donation form exempts its item. See Shipping and tax in the examples.

Donations: subscription_custom

An on-the-fly item lets the customer set the price and the schedule:

{exp:cartthrob:add_to_cart_form
    on_the_fly="yes"
    allow_user_price="yes"
    no_tax="yes"
    no_shipping="yes"
    options:subscription_end_date="any"
    return="subscriptions/view_cart"}

    {exp:cartthrob:subscription_select name="subscription" options="yes:Yes|no:No" default="yes"}
    {exp:cartthrob:subscription_select name="subscription_interval_length" options="1:every|2:every other|3:every third"}
    {exp:cartthrob:subscription_select name="subscription_interval_units" options="weeks:week|months:month|years:year" default="months"}
    {exp:cartthrob:subscription_select name="subscription_total_occurrences" options="12:12 times|25:25 times|100:100 times"}
    ...
{/exp:cartthrob:add_to_cart_form}

What to notice:

  • Each subscription_select declares the only values a customer can submit. Changing the options list changes what’s allowed. A value that isn’t listed is rejected, so a customer can’t edit the page to choose a different schedule.
  • options:subscription_end_date="any" on the form lets the customer type an end date. CartThrob checks that it isn’t in the past.
  • no_tax and no_shipping exempt the donation from tax and shipping. Remove them if your donations are taxable. See Shipping and tax in the examples.

To make every donation recurring without asking, add subscription="yes" to the form and remove the first selector.

2. The cart: view_cart

update_cart_form lets the customer change each subscription row’s terms. Each selector names its row with row_id:

{exp:cartthrob:update_cart_form options:subscription_end_date="any" return="subscriptions/view_cart"}
    {exp:cartthrob:cart_items_info}
        {exp:cartthrob:subscription_select row_id="{row_id}" name="subscription_interval_units"
            options="days:day|weeks:week|months:month|years:year"}
    {/exp:cartthrob:cart_items_info}
{/exp:cartthrob:update_cart_form}

Each selector in the example is wrapped in an {if} that lists the same values as its options. When a row already holds a value outside the list, the example shows the value as text instead of offering a selector. That way, updating the cart never changes those terms.

A Plan row keeps the Plan’s terms. When a Plan’s values happen to be in the lists, for example monthly and unlimited, the row still shows selectors, but a change made there is ignored for that row. The name and price fields are read-only.

The example labels every row as a donation (“Donation Name”, “How much is this donation for?”), including Plan and product rows. Change the wording if you sell Plans or products.

If you change a selector’s options, change the matching {if} too.

3. Checkout: checkout, save_card_checkout and order_info

checkout has two branches.

The cart contains a subscription. This is the normal case. It shows a plain checkout_form with {gateway_fields}. Use a gateway that supports subscriptions; other gateways are rejected before payment.

The cart contains no subscription. This is advanced. The example offers to turn the whole cart into a subscription with options:subscription="yes|no", so the customer pays for the cart repeatedly. The template’s comments explain two limits:

  • the cart total is charged at each renewal, not divided into instalments;
  • with Stripe Payments, offer this option on its own checkout_form with subscription="yes", because Stripe Payments decides whether to save the card when the page loads.

Most stores can remove this branch.

save_card_checkout shows save_vault_checkbox, which lets a logged-in customer choose whether to save their card during an ordinary checkout. It uses the regular store cart on purpose: a subscription checkout always saves the card for renewals, so the checkbox would have nothing to choose. Add an ordinary store product to the cart to try it; with an empty cart the page shows “You have no items in your cart”.

order_info shows the result with submitted_order_info and links to an invoice.

4. The customer account: account

The subscriptions tag lists the logged-in customer’s subscriptions:

{exp:cartthrob:subscriptions member_id="CURRENT_USER" status="open|hold|closed" order_by="id" sort="desc"}
    <h4>{name}</h4>
    Status: {if status == "closed"}Closed{if:elseif is_cancelled == "1"}Not renewing — access until {end_date format="%Y-%m-%d"}{if:else}{status}{/if}
    {if is_cancelled != "1" AND status != "closed"}Next billing: {next_billing_date format="%Y-%m-%d"}{/if}

    {payments}
        {payment_date format="%Y-%m-%d"} — #{payment_order_id} — {payment_currency} {payment_order_amount} — {payment_status}
    {/payments}
{/exp:cartthrob:subscriptions}

What to notice:

  • is_cancelled means no saved card is attached, so the subscription won’t renew. It can still be Open, with access until its End Date. Show “Not renewing” rather than the raw status. The template checks status first because the reverse doesn’t hold: a Closed subscription can keep its card reference and report is_cancelled as false. See Subscription statuses and access.
  • The {payments} pair lists each payment Order. When older history is missing, it tells you so instead of showing a zero. See Payment history.
  • The links to change the card, change Plan or cancel are shown only when they apply. For example, Change Plan appears only when allow_modification is on and the subscription is Open, renewing and not behind on payments.

The example also prints a long diagnostic table (Can Renew, Is Delinquent, Computed End Date and so on) so you can see every variable. Trim it to what your customers need.

5. Managing a subscription

Each management page first loads the customer’s own subscription, so customers can’t open someone else’s:

{exp:cartthrob:subscriptions member_id="CURRENT_USER" id="{segment_3}" status="open|hold"}
    {if no_results}This subscription can't be changed.{/if}
    ... form ...
{/exp:cartthrob:subscriptions}

Changing the card: update_subscription

update_subscription_form with vault_mode="choose" lets the customer decide what happens to the card:

  • add a new card for this subscription only;
  • update the card it already uses, which also changes it for any other subscriptions sharing that card. The {other_subscriptions} variables list them.

Changing the card does not change the price, schedule or Plan. When it’s done, the customer returns to account.

Changing a card needs a gateway that saves a customer record with the card, such as Stripe or Authorize.net CIM. Offline Payments can’t update a card: on a test store that uses it, the form shows “This subscription payment method cannot be updated right now”.

One checkout saves one card for every subscription in that order. Choosing Update this saved card changes it for all of them; the {other_subscriptions} list shows which.

Changing Plan: change_plan

change_plan_form, with plan_select_field listing the other Open Plans. The page shows the customer’s unused balance, which is applied to the new Plan.

The new Plan takes effect immediately. The current subscription is closed and a new one starts on the new Plan, with that Plan’s regular price, schedule and Permissions. The new Plan’s trial is for new purchases only. Access to content granted only by the old subscription ends.

The example sets charge_difference="yes" and refund_difference="yes". The customer is charged, or refunded, the difference for the unused time. The tag’s defaults are no for both, so remove these parameters if you don’t want money to move on a Plan change. Credits require Purchased Items.

Cancelling: cancel_sub

cancel_sub_form:

{exp:cartthrob:cancel_sub_form subscription_id="{id}" refund_difference="yes" balance_account="no"
    return="subscriptions/account"}

The example refunds unused time (refund_difference="yes"). Remove that parameter to cancel without a refund. The customer then keeps access until the end of the period they paid for. A paid trial is never refunded; it runs to the end of the trial.

After cancelling, the customer returns to account, which shows “Not renewing — access until” the paid-through date. See Cancellation outcomes.

6. Protecting content: members

members shows content only to a logged-in customer whose subscription grants the demo Permission. The installer writes that Permission’s ID into the template:

{preload_replace:demo_permission_id="12"}

{exp:cartthrob_subscriptions:has_subscription_permission member_id="CURRENT_USER" permissions="{demo_permission_id}"}
    {if no_results}
        <p>Your account does not currently have access to this content.</p>
    {/if}
    <h2>Welcome to your members content</h2>
{/exp:cartthrob_subscriptions:has_subscription_permission}

What to notice:

  • The Permission ID is explicit. Leaving permissions out would accept any subscription Permission the member has.
  • Access follows the subscription, not just the assignment. It ends at the End Date, and a refunded cancellation ends it at once. See Subscription statuses and access.
  • Logged-out visitors see a login form, and the page explains when no Permission is configured (an ID of 0).

The sample product grants the demo Permission. A Plan you create grants it only if you add it to the Plan’s Permissions.

Adapting the examples for production

  • Remove development aids: Plan ID labels, the diagnostic rows in account, and the Plan ID and Item ID lines in update_subscription.
  • Require login on the account and management pages, and on checkout if you sell subscriptions.
  • Use one subscription-capable gateway in your checkout forms.
  • Decide the money policy for Plan changes and cancellations (the charge_difference and refund_difference parameters) instead of keeping the examples’ defaults.
  • Point return and link URLs at your own templates. Some examples link to the store group’s pages.
  • Protect your content. Wrap members-only content in has_subscription_permission, as the members example does. Name an explicit Permission ID in permissions; leaving it out accepts any subscription Permission the member has. Use has_subscription_permission, not has_permission, so access ends with the subscription. See Sell your first subscription.