Charge Upgrade Documentation

Set Length Plans

When setting up a recurring payment or membership subscription, you may want to have it automatically expire after a set time. Set Length plans let you do just that.

Note: We rely on the Stripe Webhooks to keep track of when plans expire, so you'll need to set these up to have your plan's expire correctly

Set Length plans can be used with both recurring payments, and subscriptions that are tied to either recurring payments or one-time charges. This can be very flexible, and easily used to setup scenarios like a $99 one-time payment for a year's membership, a recurring donation of $10 for 6 months, or a 12 month membership, with payments every 3 months. It's all handled the same way.

Setting it up

To setup, just add a couple of parameters (or form fields if you want it to be controlled by the customer) to your payment form, called 'plan_length', and optionally also 'plan_length_interval'. For example, if we want simple year's membership tied to a subscription we'd have a form similar to :

{exp:charge:form
    plan_amount="99"
    on_success="yearly_membership"
    plan_length="12"}

    // Standard payment fields ..

{/exp:charge:form}

That's literally all you'd need to do to set it up. Charge will handle the rest.

The plan_length will be calculated based on the defined plan_interval, or default to 'month', if that's not set. You can control that directly by setting 'plan_length_interval'. For example, if we want a subscription that lasts 6 weeks :

{exp:charge:form
    plan_amount="25"
    on_success="sixweek_subscription"
    plan_length="6"
    plan_length_interval="week"}

    // Standard payment fields ..

{/exp:charge:form}

Note: Set length plans must be between 1 week and 1 year in length.

You may want to use this with recurring payments too. That's just as easy. Lets setup a recurring payment that recurrs every week, and expires in 6 months :

{exp:charge:form
    plan_amount="25"
    plan_interval="week"
    plan_interval_count="1"
    plan_length="6"
    plan_length_interval="month"}

    // Standard payment fields ..

{/exp:charge:form}

You might want to let your customer pick the length of their plan, for example, to setup a regular donation for 3 months. Use the same param names, but as form fields for this :

{exp:charge:form}

    // Standard payment fields ..

    Set A Length for the Donation :
    <select name="plan_length">
        <option value="">Forever</option>
        <option value="3">3 Months</option>
        <option value="6">6 Months</option>
        <option value="12">12 Months</option>
    </select>

    // .. etc

{/exp:charge:form}

Note: You can pass an empty string for plan_length, and it'll simply be ignored and created without an automatic expiry

Front-end Variables

Within the {exp:charge:info} tag you can use following variables related to set length plans:

{plan_length_expiry}

The timestamp of when the plan is set to expire. ie. 'Your Plan will expire on {plan_length_expiry format="%Y-%m-d"}'

{plan_length}

{plan_length_interval}

The details of the plan length as defined at payment time.

{status}

The status of the payment. Normally 'active' or 'cancelled', but set length plans can also be 'expired'

{timestamp}

The timestamp the payment was originally created on

{ended_on}

If the payment has expired or has been canceled, the timestamp for that

Full docs on the variables available in the {exp:charge:info} tag

Some things to note :

• Set Length Plans & One-time Charges

  Under the hood we use the Stripe api to keep track of lengths. When using set lengths with one-time charges, we actually create a recurring payment for that period, and immediately cancel it, with the api flag 'at_period_end'. You'll see your one-time charges appearing as recurring payments that are immediately canceled. This is the expected behavior. Later, when the length has expired, we receive a Stripe event via the webhook, to tell us the payment has expired.

  In your Stripe dashboard, it'll look something like this :

  

• Expiry Periods & Recurring Payments with Different Intervals

  If you're using set length plans and recurring payments where the interval types are different : ie. A payment recurs monthly, but has a set length of 6 weeks, the final actual length of plan will run to the final billing period. In this case, that'd end up being 2 months. For best results, it makes most sense to keep the plan_interval and plan_length_interval to the same value (which is also the default behavior).

• Early Cancellation

  If you're presenting the option for self-service to users using the {exp:charge:act} tag, the customer will be able to cancel their plan earlier than the set expiry. This is all handled seamlessly, and changes the state of the payment from 'active', to 'cancelled', instead of the normal 'expired' when the final expiry happens