Subscription Products (Recurring Profiles)

Zoey allows you to set and configure "recurring payments" on any product. These are most often used for subscriptions or products with installment payment plans. When a product like this is purchased from your store, the customer is redirected to a 3rd-party payment system (PayPal Express Checkout) where a “recurring payment agreement” with the store is signed/authorized by the customer.  A recurring payment agreement is an agreement between the customer and the store authorized at the side of a payment system. In the payment system, this agreement authorizes the merchant to charge the customer account again in the future according to the recurring profile settings.

These are called “recurring profiles” in Zoey. In the 3rd-party payment system, a recurring profile is an accounting record that captures payments on a regular basis and according to the payment schedule defined in the recurring profile. A recurring profile submits the information about the frequency of a payment being initiated to the payment system. Currently, by default, Zoey supports purchasing items with recurring profiles only for the PayPal payment system and only through the Express Checkout method.

BEFORE YOU GET STARTED, SOME IMPORTANT NOTES:

• Recurring Billing will currently only work with PayPal Express Checkout. No other checkout method will work. 
• You can not have a Subscription Product in your cart with non-subscription products (regular one time purchase items). 
• Subscription Product Shopping Carts will have 0.00 in the Subtotal and Grand Total. Recurring Billing totals will appear below the Grand Total.
• Only Flat Rate, Table Rate, Product Rate and Free Shipping methods will work for Subscription Products. Calculated Rates (such as USPS or UPS) will be disabled for Subscription Product Checkout. 

The following is the general lifecycle of a recurring profile in Zoey:

1. Merchant sets up recurring profile on products which are either simple or virtual product types
2. Customer adds a product with a recurring profile to his/her shopping cart
3. Customer selects the PayPal payment method and is redirected to the PayPal payment system
4. PayPal payment system creates a recurring profile with a payment schedule defined
5. Customer is redirected to your store to complete/place their order
6. Zoey creates an order and the recurring profile ID is provided to the customer

Understanding Recurring Profiles

By default, only Simple and Virtual product types are preconfigured to have recurring profiles. For these product types, you can enable Recurring Profile in the Advanced tab when editing a product. (Catalog > Products). These parameters will be displayed on the product page on the front of store.

• Need a product that is not Simple or Virtual to have a recurring profile?
  Whether product types can have a recurring profile is defined using attributes. Specifically using the is_recurring and recurring_profile system attributes, which are included in every attribute set assigned to the product. Depending on your needs, you can enable recurring profiles for other product types (like Grouped, Configurable, Bundle, and Downloadable) using these two system attributes. To do so, in the Admin Panel, go to Catalog > Manage Attributes. Select first the is_recurring and then the recurring_profile system attributes from the list. For each, in the Attribute Properties panel go to the Apply To field and add the product type you for which you want to allow recurring profiles.

After a recurring profile is enabled for a product, the product becomes what’s called a nominal item. Nominal items do not differ from regular products in terms of catalog navigation, layered navigation, price indexing, RSS, and so on until they are added to the shopping cart. Then they differ from regular products in the following way:

• Nominal items are not added to regular totals (taxes, subtotal, and grand total).
• Subtotal, tax, shipping, and other nominal charges are separately calculated for a nominal item.
• All nominal totals are summed into the nominal grand total.
• Payment methods available for nominal products are limited to PayPal Express Checkout only.
• The list of available shipping methods during the shopping cart checkout is restricted to the fixed only (Fixed, Table Rates, and Free).

In the shopping cart, the totals for a nominal item are presented as follows:

• Initial Fee
• Trial Payment – if set, replaces the regular payment in the nominal grand total calculation
• Regular Payment – stands for a nominal item subtotal

Important Note

Currently no more than one nominal item can be added to the shopping cart at a time. A nominal item and a regular item cannot be added to the shopping cart simultaneously. This happens because of the current order submission rules – while an order in Zoey is submitted only once and regular items must be submitted as an order, each recurring profile must be submitted separately.

What the Customer Sees

When recurring profiles are set up for the products you’ll offer on a subscription or payment plan basis, the customer will see the payment profile parameters as product additional information on the Recurring Profile tab of the product view page in the frontend. Also, in the Recurring Profile Start Date field, the customer can choose the date when to start the recurring profile if this is set up in the recurring profile settings in the backend.

When the customer adds a product with a recurring profile to the shopping cart, the recurring profile schedule information and the profile start date are displayed as part of the shopping cart product description. If the customer is not allowed to or does not specify the recurring profile start date, by default, it is set to the current date.

For products with recurring profiles, the customer can only choose between the fixed-price shipping methods (flat, table or free) when checking out. After choosing the payment method, the customer is redirected to the payment system where a recurring payment agreement for payments is created. After the customer returns to the Order Review page, the order can be placed. Below is an example of a weekly recurring profile.

Note

The current version of Zoey supports purchasing a product with the recurring profile using only the PayPal Express Checkout payment method.

The order is created and the recurring profile payment reference ID is provided to the customer on the thank you, or order confirmation, page.

The customer can view created recurring profiles on the Recurring Profiles tab of her or his customer account in the frontend. From there, the customer can open the profile and view the information on item purchased, profile and payment schedule, related orders, etc. From the My Account area, the profile can be activated, canceled, or updated according to its state in the payment system.

Setting Up a Recurring Profile for a Product

By default, a recurring profile is not enabled on products when they are created. You need to explicitly enable the recurring profile option for each product that applies to. The recurring profile parameters specified in Zoey are then transferred to the payment system when the customer submits a recurring payment.

Follow along to set up a recurring profile for an already created product of a Simple product type:

1. In the Zoey Control Panel, choose Catalog > Products and select the product you want to edit from the list.
2. On the resulting Edit Product page, select the Advanced Tab
3. Set the Enable Recurring Profile field to Yes. As a result, additional fields for configuring the Recurring Payment Profile for the product become available so that you can define the payment/billing schedule, whether a trial period is offered and any initial fees.
4. In the Schedule panel, you can set the following values:
• Customer Can Define Start Date—This parameter defines whether the customer can choose the date when the recurring payments for the selected product will start. The Recurring Profile Start Date becomes available on the product view page in the frontend.
• Schedule Description – Provide a short description for the recurring payment. The description will be displayed on the review information page of the payment system as the name of the recurring payment. If the Schedule Description field is left empty, the name of the selected product will be displayed as the name of the recurring profile.
• Maximum Payment Failures—The recurring profile will automatically be suspended if the number of failed scheduled payments exceeds the value specified.
• Auto Bill on Next Cycle—Choose whether the payment system will initiate a payment transaction after the regular billing cycle set in the recurring profile settings is finished. The customer is charged in the next billing cycle if the regular billing cycle had a number of payment failures and the customer account in the payment system has an outstanding amount.
5. In the Billing panel, you can set the following values: 
• Billing Period Unit – (required) Specify the unit for billing the customer during the subscription period. The payment system will initiate a payment transaction for a recurring profile daily, weekly, biweekly, monthly, or yearly.
• Billing Frequency – (required) Specify how often within the billing period unit the payment system will initiate a payment transaction for the recurring profile.
• Maximum Billing Cycles – Limits the number of payments. Specify how many subscription periods are allowed for the recurring profile being created. If you do not specify the maximum of billing cycles, the recurring profile is permanently active and the customer will be charged by the payment system until the recurring profile is suspended or canceled.
• Example--In order to set up a product with monthly subscription payments, the following parameters would be specified on the product’s recurring profile. The customer will be charged by the payment system once a month for a year.
• Billing Period Unit – “Month” 
• Billing Frequency – “1” 
• Maximum Billing Cycles – “12”
6. In the Trial Period panel, you can set up a trial period for a product. In this case, the customer pays special trial price for a product during a period of time specified here. After the trial period finishes, the customer is charged with a regular subscription product amount. You can set the following values:
• Trial Billing Period Unit - Specify the unit for billing the customer during the subscription period
• Trial Billing Period Frequency - Specify how often within the billing period unit the payment system will initiate a payment transaction for the recurring profile
• Trial Billing Period Cycles - Limits the number of payments in the trial period.
• Trial Billing Amount - Specify the product price for the trial period in the Trial Billing Amount field. Currently, Trial Billing Amount is a global parameter.
• Note--The trial billing period parameters are optional, but if specified, make sure that all fields are populated; otherwise the payment system will not authorize the payment.
• In the Initial Fees panel, you can set the following values:
• Initial Fee—Enter the amount that the customer will be charged as soon as the recurring profile is subscribed. The initial fee is paid only once during the life of a subscription.
• Allow Initial Fee Failure—Choose whether the payment profile is suspended if the initial fee payment fails. In case the field is set to No, the initial fee will be added to the customer’s outstanding amount and will be charged by the payment system as soon as the customer account has the sufficient amount.
7. Click the [Save] button to save your settings.

Managing Recurring Profiles in the Control Panel

When an order for a recurring profile is submitted to the payment system, the latter generates a payment reference ID and returns it to Zoey. In the payment system, the reference ID contains the information about the recurring profile – its billing period unit, frequency, and billing cycle. According to this information, the payment system periodically initiates payment transactions and sends the payment reference ID and the amount charged to the customer for the subscription back to Zoey.

The list of all recurring profile records created in Zoey can be located under Sales and going to View Subscriptions. Here, the store administrator can view, update, suspend, or cancel recurring profiles.

Each action initiates a status update from the payment system. A recurring profile can have a number of states listed below:

• Pending – the profile is not active yet. The recurring profile start date specified by the customer is in the future. A profile of this state can be either canceled by clicking the Cancel button or activated by clicking the Get Update button. The recurring profile becomes active in Zoey only after it is activated in the payment system.
• Active – a regular state for receiving instant payment notifications from the payment system and for receiving payments. A profile of such state can be either suspended or canceled by clicking he corresponding buttons. The store administrator can activate a suspended recurring profile by clicking the Activate button.
• Suspended – a temporary inactive profile. A profile of such state can be either activated or canceled. A recurring profile can be suspended by the customer or the store administrator; it can also be automatically suspended by the payment system when a scheduled payment fails (if this is set up in the payment profile settings).
• Canceled – a permanently inactive profile. A recurring profile can be canceled by either the customer or the store administrator.
• Expired – a profile gets such status when its subscription period is completed.

The Related Orders tab lists the orders which have been created according to the payment system notifications referenced by this recurring profile.

Important: To have information updated on the Recurring Profile View page, Instant Payment Notifications (IPN) must be set up in merchant account of the PayPal payment system. You can use the following URL for Paypal IPN: http://[INSERT YOUR STORES URL HERE]/index.php/paypal/ipn/.

For each payment notification received from the payment system, one or more order items are created in Zoey and an order with an invoice is created for them. Depending on the payment system, different notification combinations are possible: