How the subscriptions engine works

The subscriptions engine uses orders and invoices to determine whether a specific subscription is active for a given customer at a given moment. When somebody orders a subscription, LemonStand creates an regular order. The order contains an order item, which refers to the subscription product. The order item has two fields, which determine the time interval - subscription start day and subscription end date.

Once the customer pays the order, she can use the subscription during the interval defined in the order item. You can find subscription start and end dates on the Order Preview page, in the order item list.

When the subscription expires, LemonStand can generate a new invoice, with an order item having the subscription start and end dates shifted to a number of days corresponding the subscription renewal interval defined in the subscription plan.

Thus, a subscription is considered as active if there is a paid order or invoice containing the subscription products and with the start and end subscription dates which include the current date. Also, a subscription activity can affected by other subscription plan parameters - the grace period and trial period.

Please note that an order can have multiple subscriptions (if your store front-end pages allow customer to subscribe to multiple subscription products simultaneously).

Grace and trial periods

For newly ordered subscriptions the subscription start date is undefined (open), until the order is paid. Thus, if somebody places a 10-day subscription on October 15 and pays it on October 20, he can use the subscription from October 20 to October 30. However if you have a grace period defined in the subscription plan, the subscription start date will match the order date, because the grace period allows customers to begin using a subscription before they paid the order. Using the previous example, if there is a grace period defined, the customer can begin using the membership starting from October 15 (right away after placing the order), but if he pay on October 20, he will have only 5 days before the subscription expires, because he already used 5 days of the grace period.

Trial periods are considered as periods of free usage and do not affect the subscription start date. If you have a trial period defined, the customer can place the order on October 15, and start using the membership right away. If he pay the order on October 20, he can use the subscription 10 days more, i.e. until October 30.

What are invoices

In LemonStand invoices are orders which are bound to the original order. When a customers' subscription ends, LemonStand generates a new invoice, and bind it to the original order. You can find invoices generated for a specific original order on the Order Preview page, on the Invoices tab. This tab is visible only if an order contains any subscription products.

If you click an invoice in the list, you will get to the invoice preview page. This page is a regular order preview page, but in the left top corner you will see a link to the parent order:

By default LemonStand does not show invoices in the order list. When invoices are supported by the system (for example, when the Subscriptions Module is installed), LemonStand displays the Show Invoices checkbox in the order list filters area.

Generating subscription invoices

There are two ways to generate subscription invoices - manually or automatically. To work properly, the subscriptions engine requires you to run the invoice generating script every day, so the automatic invoice generating is preferred.

To generate invoices automatically, you should access the following URL in your LemonStand store: /ls_generate_subscription_invoices. The exact script location depends on your LemonStand installation URL. If you installed LemonStand to http://www.example.com, than the script URL would be http://www.example.com/ls_generate_subscription_invoices. You can setup a cron job to invoke the script daily. You can use CURL application for invoking the URL. Example cron job command:

curl http://www.example.com/ls_generate_subscription_invoices

To use the automatic invoice generating, you need to add the IP address of the server you run the cron job on, to the list of allowed IP addresses in your LemonStand installation. Please define the CRON_ALLOWED_IPS parameter in your config/config.php file. Example:

/*
 * Cron access 
 */
  
$CONFIG['CRON_ALLOWED_IPS'] = array('127.0.0.1');

When the subscription engine generates new invoices, it analyzes all subscription products in each order and includes to new invoices only expiring subscriptions. If an order contains two subscriptions - monthly and yearly membership, the monthly subscription product will be included into a new invoice each month, while the yearly subscription will be included into an invoice only once an year.

LemonStand logs the invoice generating process with a special trace log listener called INVOICE_GENERATING. By default there is no log file for this listener. If you want the invoice generating process to be logged to a file you should configure the listener in the config.php file:

/*
 * Save the invoice generating log to /logs/invoice_generating.txt
 */

$CONFIG['TRACE_LOG']['INVOICE_GENERATING'] = PATH_APP.'/logs/invoice_generating.txt';

Also LemonStand sends the invoice generating report to the system administrators. You can customize the message template with altering the email template with code subscriptions:invoice_generating_report. Do not remove the {invoice_gen_report} variable from the template text.

Creating invoices manually

You can force automatic invoice generating for a specific order by clicking the Generate subscription invoice button on the Invoices tab of a parent order. This action will generate new invoices only in case if the order contains expiring subscriptions.

Alternatively you can create an invoice manually, even if the subscription is not expired. To create an invoice manually, click the Create invoice button on the Invoices tab.

This opens the Edit Order page, where you can define subscription start and end dates for each subscription-type order item. To edit the subscription start or end date, click an item in the order item list and go to the Subscriptions tab.

Configurable Paid order status

On the System/Settings/Subscriptions Settings page you can set another order status to be considered as Paid status by the Subscriptions engine. 

Configuring the automated billing

LemonStand Shop module includes the automated billing feature which utilizes the customer payment profiles feature internally. The automated billing feature can bill customer saved credit cards for each invoice. The automated billing processes only invoices - the initial subscription orders still should be paid manually.

To configure the automated billing feature, open the System/Settings page and click the Automated Billing Settings link.

In the configuration form you can enable the feature and choose a payment method which should be used for the automated billing. Only payment methods which support the customer payment profiles can be used. Also you can choose email templates to be sent to customers in case of successful or failed credit card billing. In the email template you can use any order or customer template variable. Below is the example content for the automatic billing success notification:

We would like to notify you that your credit card payment for services you purchased has been processed and approved.
Please see the invoice details below.

Invoice #: {order_id}
Invoice date: {order_date}
Amount paid: {order_total}

{order_content}

If you believe you have been incorrectly billed, would like to change your credit card details or have any
other questions regarding your account with us, you may open a ticket at our Support Helpdesk.

Please note that the automated billing feature requires the cron job to be configured for invoking the /ls_shop_auto_billing URL daily. Define the CRON_ALLOWED_IPS parameter in your config/config.php file as it is described above in the Generating subscription invoices section.

When LemonStand processes automated billing it logs the process with a special trace log listener called AUTO_BILLING. By default there is no log file for this listener. If you want the automatic billing to be logged to a file you should configure the listener in the config.php file:

/*
 * Save the automated billing log to /logs/auto_billing.txt
 */

$CONFIG['TRACE_LOG']['AUTO_BILLING'] = PATH_APP.'/logs/auto_billing.txt';

Also LemonStand sends the automated billing report to the system administrators. You can customize the message template with altering the email template with code shop:auto_billing_report. Do not remove the {shop:autobilling_report} variable from the template text.

If the automated billing fails, the customer should visit the store and enter the credit card details to the payment form, and optionally - save the updated credit card information to be used next time.

Pausing and resuming subscriptions

The Subscription Chart allows you to pause and resume subscriptions. When a subscription is paused, it is considered as inactive even if there is a paid invoice which includes a current date. Also, LemonStand does not generate invoices for paused subscriptions.

Cancelling subscriptions

You can cancel a subscription from the Edit Order page. Click a subscription order item and then check Subscription cancelled checkbox on the Subscription tab. Cancelled subscriptions do not renew. Alternatively you can mark an order containing a subscription deleted. This effectively cancels all subscriptions in the order.

Next: Subscriptions and discounts
Previous: What is a subscription and a subscription plan
Return to Subscriptions module