X-Cart:Subscriptions

IMPORTANT!
The Subscriptions module is a recurring billing solution that was available for X-Cart versions prior to 4.4.0. This solution is not PCI compliant and we no longer encourage its use in X-Cart stores of any version.
For X-Cart versions 4.4.5 and later we provide a newer, PCI compliant solution: X-Payments Subscriptions and Installments.

What Subscriptions module does

Subscriptions is an X-Cart module that allows you to use recurring billing. If your store has to deal with regularly scheduled payments (such as membership dues or installment payments), this module can take a load of work off the shoulders of the staff involved with processing them.

With Subscriptions, your customers' accounts can be charged automatically. You specify, which products in your store should be available by subscription, and set up a recurring billing plan for each of these products. A recurring billing plan includes information about the amount and frequency to be charged to a customer's credit card.

Note: if you want to use recurring billing, make sure you disable the anonymous checkout option, otherwise the billing cannot be performed as no credit card data will be stored in the anonymous customer's profile.

When customers order a subscription product, they consent to allow your store take payments from their account at regular periods of time. Then, a special script, which can be launched either manually or automatically, uses the billing information contained in the customers' profiles to charge an appropriate amount to their credit cards. An optional email can be sent to the orders department of your store every time a customer's account is charged to help you monitor your recurring billing transactions.

In any case, using the module reduces processing time and administrative hassle, reduces risk of human error from manual processing and provides you better control over your cash flow.

Important: Please be aware that if you want your store to be able to perform periodic billing transactions with Subscriptions module, the values of the $store_cc and $store_cvv2 variables in config.php must be set to 'true'. For more info please refer to: Storing Customers’ Credit Card Info and Storing CVV2 Codes

Roles in Subscriptions module management

If you are an X-Cart GOLD administrator/provider or an X-Cart PRO administrator:

• You can enable/disable Subscriptions module and adjust its configuration settings (Check out #Enabling and Configuring 'Subscriptions').
• You can perform all operations regarding subscription management in your store: search for existing subscriptions, view the details of subscription orders, change future pay dates, activate/disable/cancel subscriptions, etc (Study #Managing Subscriptions).
• You can manually charge accounts of customers signed up for a recurring billing plan or set up an external application that will charge these accounts automatically (See #Running admin/pay_subscriptions.php).

If you are an X-Cart PRO provider:

• You can specify, which products you would like to be paid for on a recurring basis and set up recurring billing plans for these products (See #Adjusting Setup Fees and Recurring Billing Plans).

Enabling and Configuring 'Subscriptions'

To begin using the module:

1. Open the file config.php in a text editor. Set the values of the $store_cc and $store_cvv2 variables to 'true'. Save the file.

2. Enable Subscriptions module (Administration menu->Modules).

When the module is enabled, you can see:

1. Subscriptions item in the Management menu;
2. Subscriptions link in the 'Product Management' section menu (when a product is opened for editing);
3. Subscriptions options section in General settings/Modules options.

3. Adjust the module settings via General settings/Modules options->Subscriptions options.

a) If you are going to run the admin/pay_subscriptions.php script from the command line or to automate recurring billing using a scheduling program (like cron), set a secret key for your Subscriptions module. A secret key must consist of alpha-numeric symbols and can have up to 64 symbols.

b) Specify if you want notifications to be sent to the orders department after billing has been performed.

Note: The text of the recurring billing email notification is hard-coded in admin/pay_subscriptions.php.

c) Click the Save button.

To be able to process subscription payments automatically you need to set up Subscriptions processor. See the #'Payment methods' section for more information.

Adjusting Setup Fees and Recurring Billing Plans

If you want to sell products using subscription, you need to define a subscription setup fee and a recurring billing plan for each of these products.

To define a subscription setup fee for a product:

1. Find the product for which you want to set up a recurring billing plan. Open this product for modification in the 'Product Management' section.
2. Enter the desired setup fee into the 'Price' filed.

To set up a recurring billing plan for a product:

1. Find the product for which you want to set up a recurring billing plan. Open this product for modification in the 'Product Management' section.

2. Click the Subscriptions link in the 'Product Management' section menu. 'Subscription' dialog box will be opened.

3. Complete the fields of the 'Subscription' dialog box:

a) Specify the frequency at which a customer's account should be charged:

• select Annually, Quarterly, Monthly or Weekly from the 'PAY PERIOD' drop-down box, or
• select By period from the 'PAY PERIOD' drop-down box and enter your own period into the field below. The period must be specified in days.

b) Specify a period fee - an amount that will be charged to a customer's account per period. For example, if a monthly payment must be $20, you should enter 20.00 into the 'PERIOD FEE' field.

c) Use the 'COST OF ONE DAY' field to specify how much it will cost to use the product for one day.

d) Use the 'DAYS SAME PERIOD' field to specify the number of days in the period specified in the 'PAY PERIOD' field.

Note: Adjusting the 'COST OF ONE DAY' and 'DAYS SAME PERIOD' fields enables your customers to sign up for recurring billing plans at any time, without having to wait till the beginning of the next pay period.

Example:

You would like to set up a recurring billing plan for a certain product so that regular payments of $20 are taken from the accounts of customers who purchase this product monthly (say, on the 10th day of the month). You set the ‘PAY PERIOD’ field to Monthly and the 'PERIOD FEE' field to 20.00. Assuming the product's setup fee is set to 0.00, a customer who signs up for the recurring billing plan on May 10th will be supposed to pay $20 at once, then another $20 on June 10th, then $20 on July 10th and so on.

Now think of a situation where a customer comes to your store on May 1st and signs up for the recurring billing plan. How much is this customer supposed to pay? It does not seem fair to charge him the full period fee amount of $20 on May 1st, as he will be supposed to pay $20 again in just 10 days. Subscriptions module helps you handle this situation using the values of 'COST OF ONE DAY' and 'DAYS SAME PERIOD' fields. As his first payment, the customer who signs up for the recurring billing plan 10 days before the established pay date will only be charged for the time he uses the product in the current period (10 days). To find out how much money the customer is supposed to pay for 10 days, Subscriptions module will multiply the cost of one day of using the product (the value of the 'COST OF ONE DAY' field) by the number of days before the next pay period (the value of the 'DAYS SAME PERIOD' field). In our example, the cost of one day is $20.00 (period fee) / 30 days (the average number of days in a month) = $0.666667; the number of days before the next pay period is 10. This means that the cost of using the product for 10 days before the next period is approximately $6.67

The sum that will be charged to your customer's account on May 1st will be calculated according to the formula 'setup fee + cost of using the product for 10 days' ($0.00 + $6.67) and will equal $6.67.

4. Click the Apply button. Pay dates button will appear.

5. Click the Pay dates button. Use the calendar to select the dates on which payments will need to be taken.

You might want to accept the dates offered by the program or select different dates. All the selected dates can be unselected with one click (use the Reset to empty button). To select a pay date, click on the appropriate date in the calendar. The date will be highlighted. To unselect a date, click on it once again. You will be able to return to the first variant offered by the program at any time by clicking on Reset to... (your pay period) button. As soon as you are satisfied with your payment schedule, click the Update button.

To delete a recurring billing plan:

1. Find the product you want to delete a recurring billing plan for. Open this product for modification in the 'Product Management' section.
2. Click on the Subscriptions link in the 'Product Management' section menu. 'Subscription' dialog box will be opened.
3. Click the Delete button at the bottom of the 'Subscription' dialog box. The dialog box fields should be cleared.

To modify customer's credit card information:

1. Select Settings -> General settings on the administration menu.
2. Under the Payment options section, adjust the Do not ask customers to enter CC information while getting registered setting.

Turning this option ON disables modifying customer's credit card information once an order has been placed; in this case, the store uses the credit card information provided with the order.

Turning this option OFF enables modifying customer's credit card information on the profile; that is the credit card information used for the subscription payment.

Managing Subscriptions

Existing subscriptions can be managed through the 'Subscriptions Management' section of the store's Admin area. To access the 'Subscriptions Management' section, click on Subscriptions in the Management menu.

Finding subscriptions

To find one or more existing subscriptions:

1. Go to the 'Subscriptions Management' section.

2. Use the Search form to provide the details of the subscriptions you would like to be found.

Complete one or more of the following fields:

a) 'Product ID' - to find a subscription by the ID of the subscription product;

b) 'Product title' - to find a subscription by the title of the subscription product.

c) 'Customer login' - to find a subscription by the login of the customer signed up for the appropriate recurring billing plan.

3. Click the Search button.

To list all existing subscriptions:

1. Go to the 'Subscriptions Management' section.
2. Click on List all at the bottom of the Search form (without providing any details).

Subscription search results

No matter whether you search for a specific subscription or tell X-Cart to list all the subscriptions existing in your store, the search results are listed in the form of a table in the 'Subscriptions' form. The table format description provided in the upper part of the 'Subscriptions' form can help you read the table.

To view the details of a found subscription product, click on the <Product> link.

To view/modify the payment schedule defined for the product, clicking on the <Next Pay Date> link.

To view/modify the profile details of a user signed up for the recurring billing plan corresponding to the found subscription, click on the user's <Login> link.

To view/modify the details of an order corresponding to the first payment in a recurring billing plan, click on the <Date of Subscription> link (SUBSCRIPTION DATE column).

To view/modify the details of an order corresponding to the most recent payment in a recurring billing plan, click on the <Last Paid Date> link (LAST PAID DATE column).

To change the status of a customer's subscription to a certain product, use the drop-down box located in the STATUS column opposite the customer's login: select the desired status (Active, Unsubscribed or Disabled) and wait for the page to be refreshed.

(If you process payments manually) To charge an appropriate amount to a customer's credit card, click the Charge link opposite the customer's login.

Running admin/pay_subscriptions.php

To be able to accept periodic payments from customers, you will need to periodically run the script <xcart_dir>/admin/pay_subscriptions.php.

To run the script, do one of the following:

• Request that the accounts of customers supposed to make a periodic payment be charged using the controls of X-Cart Admin area:
  • Click the Subscriptions link in in the Management menu to access the 'Subscriptions Management' section.
  • Search for the customer accounts that need to be charged.
  • Click the Charge link.

• Launch the script admin/pay_subscriptions.php from the command line.

Use one of the following commands:

/usr/bin/curl --get http://www.mystore.com/admin/pay_subscriptions.php?key=secret

or

/usr/bin/wget -q -O- http://www.mystore.com/admin/pay_subscriptions.php?key=secret

or

/usr/bin/fetch -o- http://www.mystore.com/admin/pay_subscriptions.php?key=secret

where http://www.mystore.com is the address of your store and secret is your secret key for Subscriptions module.

• Adjust a scheduling program (for example, cron) to periodically run the script admin/pay_subscriptions.php. This method seems the most convenient, as the process of charging your customers' accounts becomes fully automated.

No matter which of the three methods is used to launch the script admin/pay_subscriptions.php, you do not need to remember the exact payment due date: the script charges only the accounts of customers for whom the time has come to make a payment (according to the subscription plan).

After the appropriate accounts get charged, you should find a proper number of orders placed.