Child pages
  • Subscriptions & Recurring Payments
Skip to end of metadata
Go to start of metadata
Icon
This document is relevant to the 1.X branch of the Subscriptions And Recurring Payments extension. Click here to see the readme for the actual 2.X branch

Extension page: http://ecommerce.aheadworks.com/magento-extensions/subscriptions-and-recurring-payments.html

The Subscriptions and Recurring Payments extension by aheadWorks extends Magento abilities further – now you are able to accept recurring payments and sell subscription products! Ever wished to have memberships on your site? No problem – this extension can handle that. Dreamed about having subscriptions for your physical products? This can be done as well!


Installation

Clear the store cache under var/cache and all cookies for your store domain. Disable compilation for Magento 1.4+. This step eliminates almost all potential problems. It's necessary since Magento uses cache heavily.

Backup Your Data

Backup your store database and web directory.

Download and Extract

Download and unzip extension contents on your computer and navigate inside the extracted folder.

Upload Files

Step 1

Navigate inside step_1 directory. If you use a different from default theme - be sure to rename step_1/app/design/frontend/default/default and step_1/skin/frontend/default/default folders to your store's values. Using your FTP client upload content of step_1 directory to your store root.

Step 2

Navigate inside step_2 directory and upload its content to your store root the same way as it was done in Step 1. 

Step 3

One more time clear the cache under var/cache and login to Magento backend (admin panel). In case you have already been logged in during the installation, logout and login back.

Set up cron

In order to create and process subscriptions/orders the extension needs to be launched by cron. Read the following instructions on setting cron job for your Magento store: Magento user guide. If you have already configured cron jobs for your Magento installation then you can skip this step.

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.

Important Notice

For proper work of the extension, cron must be started without initializing a web session. It means that cron must be either launched like described above, or if you run it using wget, the parameter "--no-cookies" must be added. 

Once cronjob is set up and running, the extension will be saving every action in the log, which can be viewed in System->Configuration->aheadWorks Extensions->Info->aheadWorks Extensions logging->View log. If you think that the extension does not work as expected, it is recommended to check the log first. If it is empty or contains very few records, it may indicate that your cronjob is not set or set improperly. Normally, every cron launch should add 1 or more entries. Actual quantity of the entries depends on the number of processed events per given cronjob.


Upgrade to SARP 1.9.X

After upgrade make sure that your configurable subscription products contain the products of 'simple' type, i.e. they are NOT of 'simple subscription' type. 

1.4 beta installations

If you have used this extension versions 1.0 and 1.1 running under Magento 1.4 beta, please perform full reinstallation of this extension.


Configuration

To configure the extension navigate to System > Configuration > aheadWorks Extensions > Subscriptions. Here you can define different options.

Magento setup

Go to System > Configuration > Sales > Checkout > Shopping cart and set Quote Lifetime (days) to maximum value of your subscriptions period +1 day. E.g. if your store has maximum monthly subscription you should setup this to 31 + 1 = 32 days.

Important Notice

These settings are highly important for correct functionality.


Subscription Periods

You can create any number of subscription periods in Catalog-> Subscriptions-> Periodicity tab.
When creating a subscription product (see below), you will need to select at least one period allowed for the product, to enable the subscription functionality.

Note: the subscription period defines the delay between the auto-generated orders. It is not possible so set any price modifiers linked to a specific subscription period.

Creating a subscription product

There are two ways of creating subscriptions: create a new subscription product or convert an existing simple/downloadable product to subscription. Note that in the former case you still can sell the product as a simple/downloadable item and subscription simultaneously.

Creating a new product

Create a new product in the way you usually do it, but select "Subscription/recurring payment" as product type.

Converting from existing product

Simple, configurable, grouped, virtual and downloadable products can be converted to subscription. Open the Product Information page, switch to the "Enable subscriptions" tab and click the "Convert this product to subscription product" button. The item will be converted to subscription.

After that you can switch to the "Subscription" tab and configure subscription options as you like.

Note, the children of configurable subscription products must contain simple (i.e. non-subscription) products only.


Managing subscriptions

Managing from the frontend


The customers can manage their subscriptions from a special "My Subscriptions" area in their accounts.
The customers can suspend/ cancel/ re-activate their existent subscriptions.
In case the customer needs to edit other subscription details (Payment Method, etc), they will be prompted to checkout once again, while their current subscription will be automatically cancelled.

* see Important Notes below.

Managing from the backend

All the existent subscriptions are listed and can be managed in Catalog-> Subscriptions-> Subscriptions List backend tab.

The extension only allows to update a subscription status for an existent subscription. Both the store admin and the customer can suspend / re-activate / cancel a subscription at any time.
However, the extension does not allow to change other attributes (order items, shipping/ billing details, subscription period or options, etc). If this is to be done, it would be necessary to cancel the existent subscription, and create a new one.

* see Important Notes below.

Subscriptions Statuses


the subscription can have one status at a time, the existent statuses are:

Active - the subscription is being processed normally, the extension will generate and charge new orders;
Cancelled - the subscription has been manually cancelled, either by the customer, or by the store admin;
Expired - the number of cycles specified in the subscription period settings has been reached, the subscription is no longer processed;
Suspended by customer* - the subscription has been manually suspended by the customer;
Suspended* - the subscription has been suspended either by the store admin, or automatically (in case the latest subscription order hasn't been fully processed for some reason)

*NOTE: for the "Suspended" subscriptions, the payment schedule is not cleared. In case the store admin manually re-activates a "Suspended" subscription, the extension will charge the customer for all the missed orders at once, unless the admin skips the pending payments in Catalog-> Subscriptions-> Subscriptions List-> Edit Subscription-> Payments tab.
(E.g., if a monthly subscription has remained suspended for 3 months, once it is reactivated, the extension will generate and charge 3 orders )

Important notes

The workflow of the extension has certain peculiarities, please, pay attention to the below when managing your subscriptions:

Changing subscription-related parameters

The module retrieves the subscription details from the initial order. If you modify any subscription-related detials (delete customer or subscription product, change periodicity settings, change shipping rate or allowed shipping method, etc) while there are any active subscriptions that rely on the modified parameters, it may cause the improper work of the whole system.

Applying discount codes
    • In case the coupon code is 1-time (i.e., the "Uses Per Coupon" or "Uses Per Customer" is set to "1" in the Shopping Cart Rule settings), the discount will only be applied to the initial order.
    • In case of a multi-use coupon, it will be automatically applied to the subsequent orders within the given subscription.
Purchasing multiple subscriptions in one order

The extension does allow ordering several subscriptions at a time:

    • If all the subscription items in the cart have the same periodicity settings, the extension will create 1 multi-item subscription.
    • In case there are products with different periods in the order, the extension will create a number of separate subscriptions, one for each of the specified periods.

E-mail templates and subscription alerts

This extension can send customizable alerts. It can send them before, after or exactly when the specified event happens. You can set up the unlimited number of alerts at Catalog > Subscriptions > Subscriptions Alerts.

If you used 1.0 version previously, you have to re-customize the templates, due to changed email templates system since 1.1.

Admin notifications

Admin notifications are stored at /app/locale/en_US/template/email/aw_sarp/alerts/admin:

  • activation.html - sent when subscription is activated
  • eachdelivery.html - sent on each delivery
  • expiredate.html - sent on expiration date event
  • firstdelivery.html - sent on first delivery event
  • newsubscription.html - sent when new subscription is created
  • suspended.html - sent on suspend subscription
  • unsubscription.html - sent on unsubscription

Customer notifications

Customer notifications are stored at /app/locale/en_US/template/email/aw_sarp/alerts/customer:

  • activation.html - sent when subscription is activated
  • eachdelivery.html - sent on each delivery
  • expiredate.html - sent on expiration date event
  • firstdelivery.html - sent on first delivery event
  • newsubscription.html - sent when new subscription is created
  • suspended.html - sent on suspend subscription
  • unsubscription.html - sent on unsubscription

Templates variables/methods

  • subscription.id - ID of subscription
  • subscription.customer_name - name of the customer who purchased subscription
  • subscription.getCustomerUrl() - URL for customer to view subscription
  • subscription.getAdminUrl() - URL for admin to view subscription
  • subscription.next_delivery_date - next delivery date
  • subscription.next_payment_date - next payment date
  • subscription.first_delivery_date - first delivery date
  • subscription.customer_email - customer email address
  • subscription.products_text - products with quantity included in subscription

Payment Gateways Configuration

Authorize.net configuration

If you are going to use Authorize.net as a payment method, be sure to:

  • Configure Authorize.net at System > Configuration > Sales > Payment Methods
  • Specify correct API Login ID and Transaction Key (can be retrieved at Authorize.net account)
  • Activate CIM service at authorize.net(http://www.authorize.net/solutions/merchantsolutions/merchantservices/cim/). This extension requires CIM.
  • If you are using test API with test.authorize.net, then:
    • Register developer account at http://developer.authorize.net
    • Turn test mode off in both Magento settings and Authorize.net account
    • Specify "Use test SOAP API" at System > Configuration > Sales > Payment Methods > Authorize.net

If some errors occur, navigate to System > Configuration > aheadWorks Extensions > Info > Logging and click the View log button. All errors are kept there.

Note that in the UK Authorize.Net uses another recurrent billing API (ARB) which is currently is not supported by the extension.

PayPal Pro configuration

You need a Website Payments Pro account to use subscription functionality with PayPal. If you haven't configured a PayPal account in your store yet, you can do it at System > Configuration > Sales > PayPal accounts > Website Payments Pro and Express Checkout (API Signature). API username, password and signature are required. Then go to System > Configuration > Sales > Payment Methods > PayPal Website Payments Pro - Direct Payments and finish configuration.

This extension uses PayPal subscription service.

PayPal Pro Payflow Edition/ Paypal UK configuration

You will have to enable Reference Transactions at your PayPal manager account. To do that you should:

  1. Login to your PayPal Manager account
  2. Go to Account Administration > Manage security > Transaction Settings
  3. Set Allow reference transactions to "Yes" and click "Confirm"

ePay configuration

If you are going to use ePay as a payment method, be sure to configure it at first. You should have at least your ePay merchant ID in the ePay configuration, and it must be enabled for subscriptions. You can do this in System > Configuration > Sales > Payment Methods

You have to manually insert string in templates

  • app/design/frontend/default/default/template/epay/standard/redirect_paymentform.phtml
  • app/design/frontend/default/default/template/epay/standard/redirect_standardwindow.phtml

Find the following entry:   

 

And add right after that:  

 

Please ensure that "Integrated layout" option of ePay extension is set to "Standard Payment Window - popup (2)" because only with this value required parameters can be transfered to ePay gateway.

If "app/design/frontend/default/default/template/epay/standard/redirect_paymentform.phtml" does not exist then do the following:

  • find the following code in "app/design/frontend/default/default/template/epay/standard/redirect_standardwindow.phtml"

  • change it to the following code:


 

Icon

For Mage_Epay v 2.6.0 users

If you are using the specified version of the ePay Payment Module, you are likely to come across the following Exception:

"Cannot send headers; headers already sent in /app/code/local/Mage/Epay/Model/Observer.php, line 15"

This error can be found in the extension's log ( System-> Configuration-> aheadWorks Extensions-> Info-> aheadWorks Extensions logging-> View Log backend screen), as well as in the Magento's sytem log ( /var/log/system.log file )

To solve this problem:

  1. Open file  /app/code/local/Mage/Epay/Model/Observer.php
  2. Change this code (line 15)


    to

  3. Save the file and flush the store cache

 

 


Uninstall

  1. disable compilation, in case it is enabled.
  2. Clear the cache under var/cache
  3. make a backup and then run the following query in MySQL (Note, if you are using the tables with prefixes, you must specify them in all table names): 

This will delete the extension's attributes and tables from the database.
If you are not sure how to do that or expect any troubles with it, please contact your server administrator regarding the matter.
If you remove the tables as it is described above, you will need to reconfigure the extension completely again after the extension is reinstalled (period settings, alerts, etc). All subscriptions history will be lost as well.
After tables removal, you can safely remove the extension's files from your store:

4. Login to your FTP, navigate to 
app/etc/modules/
5. Open the file AW_Sarp.xml and change the following line:  

 

to

Now your Magento is unaware of the existence of the module.

6. Clear the cache under var/cache
7. Make sure that the site is working properly, otherwise roll back the changes, restore the database and apply to our technical support.
8. If everything works fine, it is safe to delete the files of the extension.


Troubleshooting

After the extension installation the store gives an error, or blank page, or suggests to start Magento installation procedure.

Change the owner of the extracted extension files to the web server user and set 775 permissions on them. Clear the store cache and try again.

There is no aheadWorks extensions under my configuration section, or having the extension tab clicked I get a blank page, or Access Denied error.

Clear the store cache, browser cookies, logout and login again.

I've set up everything correctly, inserted the HTML code but there is nothing on that page.

Clear the store cache, clear your browser cache and domain cookies and refresh the page.

My configuration changes do not appear on the store.

Clear the store cache, clear your browser cache and domain cookies and refresh the page.

 


You can always find the latest version of the software, full documentation, demos, screenshots and reviews at http://ecommerce.aheadworks.com
License agreement: http://ecommerce.aheadworks.com/LICENSE-M1.txt
Contact us: http://ecommerce.aheadworks.com/contacts/
Copyright © 2015 aheadWorks Co. http://www.aheadworks.com


Icon

Having hard time finding an answer to your question?

Check out our Knowledge Base.

  File Modified
PDF File SARP_1X_FAQ.pdf Dec 18, 2013 by vinokurova
PDF File SARP_1_9_1_User Guide.pdf Dec 18, 2013 by vinokurova

  • No labels