Manual Version: 1.0.0
Table of Contents I. INTRODUCTION... 3 II. INSTALLATION... 5 a. System Requirements... 5 b. Installation... 5 c. Configure PayPal IPN... 5 d. Cron Setup... 6 e. Upload Email Logo... 6 III. CREATE SUBSCRIPTION PRODUCT... 7 a. Create Subscription Types... 7 b. Create Subscription Options... 9 c. Assign Subscription Information... 10 IV. SUBSCRIPTION PRODUCT AT FRONTEND... 11 a. Product Page... 11 b. Product In Shopping Cart... 12 c. Payment Methods... 16 d. Order Review & Place Order... 17 e. Success Place Order... 19 V. CUSTOMER SUBSCRIPTIONS... 20 a. My Subscriptions... 20 b. Subscription Information... 21 c. Subscription Related Orders... 22 d. Subscription Order Email Notification... 24 e. Subscription Status Email Notification... 25 VI. SUBSCRIPTION MANAGER (BACKEND)... 26 a. Subscription List... 26 b. Subscription Information... 27 c. Subscription Related Orders... 28 VII. CONFIGURATION... 29 a. General Section... 29 b. Email Section... 30 c. Backend Listing Section... 31 2
I. INTRODUCTION The Subscriptions and Recurring Payments extension allow you to sell products on a daily, weekly, monthly, or yearly subscription basis with any duration. Offer a magazine subscription for one year with a weekly periodicity or coffee delivery each three weeks. Prices of subscription intervals can also vary from each other and you can set them up in the way you like: e. g. motivate customers to subscribe for a longer period by making this kind of subscription cheaper and thus more profitable for them. You can continue to sell these products as a one-off sale; but your customers can opt to buy a subscription if they wish - and they can do it right from your online store. As soon as a customer subscribes to any item, he/she create a recurring profile for the subscription product. All future payments will be created automatically according to recurring profile settings. You can allow customer to schedule the start day of payments or moment of purchase. The module supports PayPal Express Checkout and PayPal Pro to schedule orders in advance. So you can accept credit card and bank account payments for magazines, software licenses, or products like grocery, bottled water, memberships, pills, detergents, newsletter fees, club dues, or recurring donations, etc. The Subscriptions and Recurring Payments extension for Magento uses native business logic of payments methods and allows you to configure trial period and initial fee for each subscription period with its own prices and durations. Features: Support payment methods o PayPal Express Checkout o PayPal Pro o Check / Money Order o Zero Subtotal Checkout o Bank Transfer Payment o Cash On Delivery Payment o Purchase Order Support product types: You can add subscription options to products of simple, virtual, downloadable, configurable or bundle type. Customizable subscription options o Create custom options for the product as usual with the name of the subscription period; define the sequence of its displaying in the frontend and subscription period price. o Assign the subscription info into custom options o Define the subscription period interval unit Day Week Month Year 3
o Define the number of units in one subscription period. For example: if you want to offer coffee delivery every third week, you should configure the following: minimal unit within a period week; number of units in a period 3. o Infinite subscription type. The module allows customers to subscribe to any product once and receive the delivery forever. The payments will be created automatically. If you want to limit the duration of subscription period, you can specify the number of occurrences of the subscription type. When the subscription is expired, a customer should subscribe to it again to get the delivery. Subscription start day o Defined by customer o Moment of purchase Only subscription options With the help of the module, you can offer products that can t be purchased as a one-off sale. View subscription list o As soon as customers subscribe for a subscription product. You can view all subscriptions in the backend. o In customer Information page there is a subscriptions list tab that will list all subscriptions that belong to this customer. Native payment gateway s business logic o Trial period You can adjust one trial period per each subscription type. Offer free trial subscription or define the price different from the ordinary subscription price (these amounts will be summarized at the shopping cart). o Initial fee The module allows you to enable starting fee for any subscription. o Tax fee If the subscription product have tax then the module will auto calculate this for you o Shipping fee For simple subscription product the module will auto calculate the shipping fee base on customer select shipping method o Allow fail cycles The number of fail cycles that allow the customer subscription still in active state. Recurring profiles statistics in the admin area All PayPal payments are processed on the gateway s side, other payments are process at system cron job. You can check the following data of the recurring profiles directly in the backend: customer name, payment method, shipping method, start date, next payment cycle, profile status, etc. Recurring profile can be: o Pending o Created o Active o Suspended 4
o Canceled o Expired Subscriptions in My Account Customers can check the status and periodicity of their subscriptions, pay outstanding amount or even cancel the subscription in their account area. II. INSTALLATION a. System Requirements Support Magento Community Edition 1.6, 1.6.1, 1.6.2.0, 1.7, 1.8 All4coding Core v2.0.0 b. Installation Login to Magento Admin Panel Go to All4coding > Extension Manager Click the Install button of the extension and follow the instruction on the installation wizard to install the extension. Please Read All4coding Core Manual for more information. c. Configure PayPal IPN If you want to provide PayPal Express Checkout or PayPal Pro payment methods, you need to setup the PayPal IPN before any sales. Because the extension relies on IPN (Instant Payment Notifications) function of PayPal. Make sure that this function is configured properly for your Magento store. You need to go to your PayPal account and: 1. Click Profile on the My Account tab. 2. Click Instant Payment Notification Preferences in the Selling Preferences column. 3. Click Choose IPN Settings to specify your listener's URL and activate the listener. The following screen appears: 5
4. Specify the URL for your listener in the Notification URL field. The magento IPN Url is http://www.yoursite.com/paypal/ipn/ 5. Click Receive IPN messages (Enabled) to enable your listener. 6. Click Save. The following screen appears: d. Cron Setup In order to get the extension to work, it needs to be launched by cron. If you have already configured cron jobs for your Magento installation then you can skip the following step. Read the following instructions on setting cron job for your Magento store: How to Set Up a Cron Job Generally it would be enough to run in SSH console of your server: crontab -e And insert the following line: */3 * * * * php /<path-to-your-installation/cron.php After that exit confirming save request. e. Upload Email Logo You should upload your email logo to the Magento system to allow the send mail feature of the module work correctly. If you have already configured email logo for your Magento installation then you can skip the following step. Go to System > Configuration Click on the Design tab at General Section. Click the Transactional Email Section and upload your email logo to Logo Image field as show below 6
III. CREATE SUBSCRIPTION PRODUCT a. Create Subscription Types Go to All4coding > Subscriptions > Type Manager, click Add Type button to create a new subscription type. 7
Type Name: The subscription type name for the profile. This will be the the suffix for the subscription profile description. Max Failed Payments: The number of cycles that the subscription period allow to fail before suspend the subscription. Bill Failed Later: Indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments that have yet to be successfully paid. Period Unit: Unit for billing during the subscription period. It is one of the following values: Day Week Month Year Period Frequency: Number of billing periods that make up one billing cycle. Note: The combination of period frequency and period unit must be less than or equal to one year. For example, if the period unit is Month, the maximum value for period frequency is 12. Similarly, if the period unit is Week, the maximum value for period frequency is 52. Period Cycles: Number of billing cycles for payment period. If the value is 0, the payment period continues until the profile is canceled or deactivated. If the value is greater than 0, the payment period will expire after the trial period is finished and continue at the period frequency for Period Cycles. Has Trial: Indicate this subscription type has trial or not. Trial Period Unit: Unit for billing during the subscription trial period; required if you specify Has Trial is Yes. It is one of the following values: Day Week Month Year Trial Period Frequency: Number of billing periods that make up one trial billing cycle; required if you specify Has Trial is Yes. Note: The combination of trial period frequency and trial period unit must be less than or equal to one year. For example, if the trial period unit is Month, the maximum value for trial period frequency is 12. Similarly, if the trial period unit is Week, the maximum value for trial period frequency is 52. Trial Period Cycles: Number of billing cycles for trial payment period. 8
b. Create Subscription Options Go to Catalog > Manage Products, create a new product or modify the existing product. Our module only supports the following product types: simple, virtual, downloadable, configurable or bundle. First you have to create the subscription option for the product at Custom Options tab. Check the bellow image for more details. As you can see it is just like any other custom options (you can give them any title you want, give a better price for long duration subscription and ordering the options). Note: The subsctipion option must be drop-down or radio buttons 9
c. Assign Subscription Information After you have created the custom options and subscription types, go to Subscription Options tab for assign subscription information. Check the image below for more details. Recurring Option: which custom option you want to assign the subscription info into. This will list all the custom options that is drop-down and radio buttons. Select the subscription option that we have created at above. Note: You have to create the subscription option at Custom Options tab first in order to assign subscription info at this page. Customer Can Define Start Date: allow customer to define the start date of the subscription or not. If not the start date will be the moment of purchase. Add Subscription: click the Add Subscription button to assign the subscription info into the custom option value. o Option Value: The custom option value you want to assign the subscription info. o Subscription Type: the subscription type you want to apply. o Trial Amount: Billing amount for each billing cycle during trial payment period; required if subscription type has trial. o Initial Fee: Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrolment or set-up fees. Note:If you want to offer product that can t be purchase as a one-off sale (only subscription) then you have to assign subscription info into all subscription option values. After that we are ready to sale product at frontend. 10
IV. SUBSCRIPTION PRODUCT AT FRONTEND a. Product Page 11
There is no different between the product have subscription info and other product. Because we use the magento native custom options to create the subscription option. And only assign the subscription info into the product. So it will be compatible with other 3 rd party theme if the 3 rd party theme have the same format like the magento default theme. b. Product In Shopping Cart 12
Our module support checkout maximum 10 subscription products and other non-recurring products at the same time. So this will enhance customer experience. The additional subscription information will be added to the purchase product: Start Date: the date start date of the subscription payment Billing Period: The billing period info Trial Period: will be show if there is a trial payment. 13
Subtotal: the subtotal of the non-recurring products. It will be 0 if there are no nonrecurring products. Tax: the tax of the non-recurring products. It will be 0 if there are no non-recurring products. Grand Total: the grand total of the non-recurring products. It will be 0 if there are no non-recurring products. Subscription Items: below this will list all subscription product payment information. o Initial Fee: the initial fee for the subscription product. If 0 then this will be hidden. 14
o Trial Payment: trial payment amount for subscription product. If there is no trial period then this will be hidden. This is not including tax and shipping amount. o Trial Tax: tax for trial payment. If there is no trial period or none tax then this will be hidden. o Trial Shipping: shipping fee for trial payement. If there is no trial period or free ship then this will be hidden. o Regular Payment: billing payment amount for subscription product. This is not including tax and shipping amount. o Tax: tax for regular payment. If there is none tax then this will be hidden. o Shipping: shipping fee for regular payment. If there is free ship then this will be hidden. o Finally it is the subtotal of the first payment amount. If there is a trial period for the subscription product then this will be the subtotal of the trial payment (include tax and shipping). 15
c. Payment Methods Our module supports the following payment methods: PayPal Express Checkout PayPal Pro Cash on Delivery Check / Money order Purchase Order Bank Transfer, Save Credit Card. 16
d. Order Review & Place Order One page checkout order review 17
PayPal Express Checkout order review 18
e. Success Place Order As you can see there is an order number related to non-recurring products. This order number will be hidden if there are no non-recurring products. After that is the payment profiles created. Note: the payment profiles created, it doesn t mean the first payment has been processed. According to PayPal The profile may take up to 24 hours for activation. But the Initial amount will be charged right away, but as we test at sandbox the initial amount will not charge right away for PayPal Express. If you want to allow customer to access to the resource before the first payment is received, then you can activate it directly at the backend or you should check the Include Created Profiles configuration at backend. For more details check Configuration section. 19
V. CUSTOMER SUBSCRIPTIONS a. My Subscriptions Customers can view his subscription profiles and status from My Account > My Subscriptions Recurring Profiles: It is default Magento support recurring profiles. If you want to hide it from customers, you can configure at backend to override the recurring profiles link. Check Configuration section for more details. My Subscriptions: All customer payment profiles will be listed in here. Reference ID: is the profile ID Description: the profile title 20
Is Active: It let customers know is their payment profile is active or not. Start Date: is the start date of the subscription. Payment Method: is the payment method of the subscription. b. Subscription Information Click on the profile you want to view more information. The subscription information will be show as below Customer can cancel the payment profile by click the Cancel button. 21
If customer has failed payments then the Bill Outstanding button will be shown. Also this button will allow customer to pay the outstanding amount and reactivate the profile if it has been suspended because failed payments. Note: The outstanding amount will not process immediately, according PayPal bill outstanding will be queue. Once the outstanding payment is success, the customer profile will be activated right away (If it has been suspended). Is Active: It let customers know is their payment profile is active or not. If it is Yes then they can access the site resource. If it is No then they can t access the site resource anymore. State: It is the current state of the payment profile: Pending: When the profile is created but the initial fee wasn t received yet. Created: When the initial fee is received. Active: When the first payment has been received or activate at the backend. Suspended: When the profile has reached it max failed cycles or suspend at the backend. Canceled: When customer canceled the payment profile or cancel at the backend. At this state if customer has paid for this cycle, then the profile is still active, and customer still can access the site resource until this cycle has been expired or close at backend. It depends on the Is Closed field. Expired: When the last recurring payment is received and at this state the profile is still active and customer of this profile still can access the site resource until this cycle has been expired or close at backend. It depend on the Is Closed field Is Closed: If the payment profile is canceled or expired and the cycle payment has been received and the current cycle hasn t expired yet, then this will be Yes, otherwise this will be No. c. Subscription Related Orders You can view the related orders from this subscription, click on the Related Orders Tab and all order related to this subscription will be shown. 22
In here you will see the order related to the subscription with the Cycles it is related to. Cycle 0 is stand for initial payment. An order may be bill for more than one cycle at the same time. 23
d. Subscription Order Email Notification This is the Initial Payment email from the module when it receives an initial payment. 24
e. Subscription Status Email Notification When the subscription status has been changed then the bellow email will be send. 25
VI. SUBSCRIPTION MANAGER (BACKEND) a. Subscription List You can view all the subscriptions at backend, go to All4coding > Subscriptions > Subscription List If you want to add more columns information please checks Configuration section. You can also manage a customer s subscriptions at customer Info page. 26
b. Subscription Information The information show in here is the same as customer subscription page. The only different in here is we have more buttons. Cancel: You can cancel this subscription, when the subscription is at created or active state. Suspend: You can suspend this subscription, when the subscription is at created or active state. Activate: You can activate this subscription, when the subscription is at created or suspended state. Bill Outstanding: bill outstanding amount and reactivate the profile if it has been suspended because failed payments. You can only bill outstanding when there is a fail payment and it cannot be within 24 hours of a regularly scheduled payment for this profile. Note: You should bill the customer outstanding amount before the profile is canceled or expired. Any canceled or expired profile will not be able to bill the outstanding again. And this outstanding amount will be lost. 27
Close: You can close the profile has state is canceled or expired but the cycle payment has been received and the current cycle hasn t expired yet. Reopen: You can reopen a closed profile that the cycle payment has been received and the current cycle hasn t expired yet. c. Subscription Related Orders Click all the Related Orders Tab at Subscription Information page and the related orders with this subscription will be shown. 28
VII. CONFIGURATION Go to All4coding > Subscriptions > Configuration a. General Section Module Front Name: This is the url path of My Subscriptions (My Account > My Subscriptions) at frontend. The default link is http://www.yoursite.com/all4coding_subscriptions Current Extra Time: When create a recurring payment profile, PayPal is base on the PayPal account time zone to validate the profile start date. And sometimes we will encounter error when the profile start date is the current time. So you should add the extra time in here to make sure it works without error. Recommend Insert 3600 second in to this field. PayPal Account Timezone: You should set this to your PayPal account time zone. Because when create a recurring payment profile the start date is base on the PayPal account timezone. If this is not correct you will encounter PayPal start date error in day period. Override Recurring Profiles Url: Whether or not override the Recurring Profiles Url (Default Magento Recurring Profiles) at customer account navigation with My Subscriptions Url. 29
Include Created Profiles: If you want to let customer access your site resource after they have pay the initial fee and before the first payment is received then select Yes. Description Separator: The separator use to concatenate product and subscription type name to create the subscription description. b. Email Section Enabled: Enabled the send email or not, when the subscription status has been changed. Subscription State Confirmation Email Sender: The Sender Email Address. Send Subscription State Email Copy To: Send email copy to these email addresses (comma-separated) Send Subscription State Email Copy Method: Send email copy method (Bcc or Separate Email) Subscription Active Template: When a subscription is active then this email template will be sent to notify the customer that their profile has been active and he can access our site resource now. You can create your own email template at Transactional Emails. Subscription Suspended Template: When a subscription is suspended then this email template will be sent. You can create your own email template at Transactional Emails. Subscription Reactivated Template: When a subscription is reactivated then this email template will be sent. You can create your own email template at Transactional Emails. 30
Subscription Canceled Template: When a subscription is canceled then this email template will be sent. You can create your own email template at Transactional Emails. Subscription Expired Template: When the last payment of the profile has been received then the subscription state will change to expired and this email template will be sent to notify the customer that there subscription will be expired soon. They still can access to the site resource, until this cycle has been expired. You can create your own email template at Transactional Emails. Subscription Closed Template: When the last payment cycle has been expired or close at backend then this email template will be sent to notify the customer that the profile has been closed and he will no longer access the site resource. You can create your own email template at Transactional Emails. Subscription Reopen Template: When the subscription has been closed at backend but the last cycle hasn t expired yet, and the administrator try to reopen the subscription at backend. Then this email template will be sent to notify the customer that the profile has been reopen for active and he can access the site resource now. You can create your own email template at Transactional Emails. c. Backend Listing Section This section is allowed to display more columns at Subscription List at backend. Show ID Column: The ID of the subscription item. Show Is Closed Column: The Is Closed attribute of the subscription item. Show Max Failed Cycles Column: The Max Failed Cycles allow for the subscription. Show Total Failed Cycles Column: The Total Failed Cycles Column of the subscription. 31