Subscription Templates

Once you’ve familiarized yourself with how subscriptions work and set up your subscription plans, you’re ready to write some subscription templates.

Each gateway provides a default template for subscription actions. If you’d prefer to handle templating yourself, you’ll have to reference the gateway plugin’s documentation to see what parameters are available.

These examples are intended to get you started toward working subscriptions and specify the correct endpoints for subscription actions.

# Subscribing

For starting a subscription, the following example is a good start.

WARNING

Gateways handle subscription payment sources differently, which might impact what’s needed for your template.

This example creates a form for posting a plan selection to the commerce/subscriptions/subscribe form action:

{% set plans = craft.commerce.getPlans().getAllPlans() %}

<form method="post">
    <input type="hidden" name="action" value="commerce/subscriptions/subscribe">
    {{ csrfInput() }}

    <select name="planUid">
        {% for plan in plans %}
            <option value="{{ plan.uid|hash }}">{{ plan.name }}</option>
        {% endfor %}
    </select>

    {# un-comment to collect payment details if there isn’t a saved payment source #}
    {# {{ plan.getGateway().getPaymentFormHtml({})|raw }} #}

    <button type="submit">Subscribe</button>
</form>

There are several things to note:

  • Subscribing a user to a plan requires the user to have a stored payment source. If a user doesn’t have one, you can add it by displaying the payment form.
  • If you wish to set subscription parameters, such as amount of trial days, it is strongly recommended to make use of subscription events instead of POST data.
  • When using Stripe, it’s not possible to choose which payment source to use if more than one is saved. Stripe will use the default payment source associated with that customer.

# Canceling the subscription

To cancel a subscription you can use the following template. It assumes the subscription variable is available and set to an instance of craft\commerce\elements\Subscription, and posts to the commerce/subscriptions/cancel form action:

<form method="post">
    <input type="hidden" name="action" value="commerce/subscriptions/cancel">
    <input type="hidden" name="subscriptionUid" value="{{ subscription.uid|hash }}" />
    {{ redirectInput('shop/services') }}
    {{ csrfInput() }}

    {{ subscription.plan.getGateway().getCancelSubscriptionFormHtml()|raw }}

    <button type="submit">Unsubscribe</button>
</form>

If you wish to set cancellation parameters, it is strongly recommended to make use of subscription events instead of POST data.

# Switching the subscription plan

To switch a subscription plan you can use the following template. It assumes that subscription variable is available and set to an instance of craft\commerce\elements\Subscription, and posts to the commerce/subscriptions/switch form action:

{% for plan in subscription.alternativePlans %}
    <strong>Switch to {{ plan.name }}</strong>
    <form method="post">
        <input type="hidden" name="action" value="commerce/subscriptions/switch">
        <input type="hidden" name="planUid" value="{{ plan.uid|hash }}">
        <input type="hidden" name="subscriptionUid" value="{{ subscription.uid|hash }}">
        {{ csrfInput() }}

        {{ plan.gateway.getSwitchPlansFormHtml(subscription.plan, plan)|raw }}

        <button type="submit" class="button link">Switch</button>
    </form>
    <hr />
{% endfor %}

If you wish to set parameters for switching the subscription plan, it is strongly recommended to make use of subscription events instead of POST data.

# Reactivating a canceled subscription

To reactivate a subscription plan you can use the following template. It assumes the subscription variable is available and set to an instance of craft\commerce\elements\Subscription, and posts to the commerce/subscriptions/reactivate form action.

{% if subscription.canReactivate() %}
    <form method="post">
        <input type="hidden" name="action" value="commerce/subscriptions/reactivate">
        <input type="hidden" name="subscriptionUid" value="{{ subscription.uid|hash }}">
        {{ csrfInput() }}

        <button type="submit" class="button link">Reactivate</button>
    </form>
{% endif %}

WARNING

Not all canceled subscriptions might be available for reactivation, so make sure to check for that using subscription.canReactivate().