SUMO Subscriptions

Documentation


SUMO Subscriptions is a subscription extension for WooCommerce. Using SUMO Subscriptions, you can create and sell subscription products in your existing WooCommerce shop. SUMO Subscriptions supports simple subscription products, variable subscription products and grouped subscription products.

Requirements
The minimum server requirements and the WordPress requirements are as follows:
HOW TO INSTALL SUMO SUBSCRIPTIONS?
1. Login to your codecanyon account
2. Go to Downloads Tab
3. You will find SUMO Subscriptions
4. Download sumosubscriptions.zip (PLEASE NOTE THE DOWNLOADED FILES WILL ALWAYS BE THE LATEST VERSION)
5. Unzip sumosubscriptions.zip inside which you will find the Plugins  files i.e. sumosubscriptions.zip
6. Install SUMO Subscriptions i.e. sumosubscriptions.zip using WordPress Dashboard
7. Activate the Plugin
HOW TO UPGRADE TO A NEWER VERSION OF SUMO SUBSCRIPTIONS?
Please always test the new version in a testing site before you upgrade to the new version in your live site.

If you are using an older version and want to upgrade to the latest  version of SUMO Subscriptions then please do the following steps,

1. Login to your codecanyon account
2. Go to Downloads Tab
3. You will find SUMO Subscriptions
4. Download sumosubscriptions.zip (PLEASE NOTE THE DOWNLOADED FILES WILL ALWAYS BE THE LATEST VERSION)
5. Unzip sumosubscriptions.zip inside which you will find the Plugins files i.e. sumosubscriptions.zip
6. Deactivate and Delete the existing version of SUMO Subscriptions in your site
7. Install the latest version of SUMO Subscriptions i.e. sumosubscriptions.zip using WordPress Dashboard
8. Activate the Plugin

Please note you will not lose any settings values, data etc by  following the above steps.

If you are using an older version of the plugin and want to upgrade to the latest version, then please follow the steps given below:

Note: You will not lose any settings,data, etc by following the above steps.

 

 

 

 

Automatic Payment Workflow

 

 

Manual Payment Workflow

 

Order Subscriptions

 

 

Creating a simple subscription product

Go to Product -> Add Product

Note:

  1. Synchronize Renewals option will not be applicable for Day Subscriptions
  2. If Subscription Duration is selected as Week or Month and Synchronize Renewal is set as Do not Synchronize, then synchronized renewal will not happen.
  3. If Subscription Duration is selected as Year and 0 is set as Synchronize Renewal, then synchronized renewal will not happen.
  4. If the Subscription is a Weekly Subscription, then Synchroinzed Renewal will happen only on the specified weeks based on the Subscription Duration.
    • For example: If the Subscription is 3 Week duration and Synchronization is set as Sunday each Week, then Synchronization will happen every 3rd, 6th, 9th Sunday and so on. If a user Subscribes in between, then they will be charged only on a Syncronized Sunday. Untill that it will be considered as Trial. If Prorate is Enabled in General Settings, then Prorate will be calculated.
  5. For Monthly Subscription, Synchronized Renewals will work only if the duration is 1 Month, 2 Months, 3 Months, 4 Months, 6 Months, 12 Months and 24 Months. Synchroined Renewals will happen for Monthly Subscription based on the given month and on the upcoming months based on Subscription Duration.
    • For example: If the Subscription is 4 month duration and Synchronization is set as 1st January, then Synchronization will happen on 1st January, 1st May, 1st September and so on. In this case, if a user subscribes on December, for them synchronization will happen on 1st January. If a user subscribes on July, for them synchronization will happen on 1st September.
  6. If the Subscription is a Yearly Subscription, then Synchroinzed Renewal will happen on the year based on Subscription Duration.
    • For example: If the Subscription is 2 Year subscription and Synchronization is set as 1st January and current date is 01-10-16, then Synchronization will happen on 01-01-18, 01-01-20, 01-01-22, and so on. When a user subscribes on or before 01-01-18, then Synchronization will happen on 01-01-18. In case if a user subscribes after 01-01-18, then Synchroniztion will happen only on 01-01-20. Untill that it will be considered as Trial. If Prorate is Enabled in General Settings, then Prorate will be calculated.
  7. If Trial is enabled for the product, then Synchronized Renewal will happens after the Trial Period. If the subscription is a Monthly Subscription and the duration is 2 months with 1 month Trial period, then Synchronized Renewal will happen after first occurance of Synchroniation after Trial period of 1 Month.
    • For example: Based on the above scenario, if Synchronization is set as 1st January and the Subscription purchase date is 10th December, then Trial duration will be from 10th December to 9th January. As the Syncronization date exceeds the payment date it will check for next Syncronization date which will be occuring on 1st March. Untill that it will be considered as Trial. If Prorate is Enabled in General Settings, then Prorate will be calculated.
    • The above scenario will be applicable for Weekly, Monthly and Yearly Subscriptions.
  8. If the Synchroniztion month which is set exceeds the current year for Monthly subscription, then first synchronization will happen only on same month of Next year. Until that it will be considered as Free or Prorate will be charged if Prorate is Enabled. This is the limitation of the plugin.
    • For example: If the Subscription Duration is 2 Months, current date is 01-10-16 and synchronization is set as 01 July, then first sync will happen only on 01-06-17. Untill that it will be considered as Trial. If Prorate is Enabled in General Settings, then Prorate will be calculated.
  9. The Downloadable Products which are given in Additional Digital Downloads will be available for download under Downloads section in My Account Page once the Subscriber purchases the Subscription Product.
Creating a variable subscription product

Go to Product -> Add Product

Note:

Please refer to Note section under Creating a simple subscription product

Grouping subscription products(Only Simple Subscription products can be Grouped)

Go to Product -> Add Product

Manual Subscription Order Creation by Admin

Go to WooCommerce -> Orders -> Add Order

Payment Gateways supported for getting Automatic Subscription Payments
  1. PayPal Subscriptions API(standard PayPal gateway that comes along with WooCommerce by default)
  2. Inbuilt SUMO Subscriptions - PayPal Reference Transactions Payment gateway
  3. Inbuilt SUMO Subscriptions - PayPal Adaptive Payment gateway
  4. Inbuilt SUMO Subscriptions - Stripe Payment gateway
Configuring Standard PayPal Payment Gateway for getting Automatic/Manual Subscription Payments

Limitations of using Standard PayPal Payment gateway for Automatic Subscription:

Configuring IPN notifications on PayPal in order to manage subscriptions
Configuring inbuilt SUMO Subscriptions PayPal Adaptive Payment gateway, SUMO Subscriptions PayPal Reference Transactions Payment gateway

To configure SUMO Subscriptions PayPal Adaptive Payment gateway,

Go to WooCommerce -> Settings -> Checkout -> SUMO Subscriptions - PayPal Adaptive

To configure SUMO Subscriptions PayPal Reference Transactions gateway,

Go to WooCommerce -> Settings -> Checkout -> SUMO Subscriptions - PayPal Reference Transactions

Note:

 
Charging subscription renewal payments automatically from the subscriber's account(except PayPal subscription API)

Note: If the subscription system is not able to charge for the subscription renewals, the status of the subscription will become Overdue.

Change in status of subscription to Overdue in automatic subscription renewal(except PayPal subscription API)
Change in status of subscription to Suspend in automatic subscription renewal(except PayPal subscription API)
Change in status of subscription to cancel in automatic subscription renewal(except PayPal subscription API)
What happens if the subscriber revokes access to preapproval key?
Configuring Inbuilt Stripe Payment Gateway to handle Automatic/Manual Payments

Go to WooCommerce -> Settings -> Checkout -> SUMO Subscriptions - Stripe

Note:

Configuring SUMO Subscriptions to handle manual subscription payments

Manual subscription payments can be done by using any one of the available payment gateways or when the user doesn't pre-approve using the inbuilt payment gateways.

Example:

  1. If the subscription duration is 5 days and Reminder Notification by Email option is set as 1,2,3 then the payment remind notification email will be sent on 3,2,1 day(s) before subscription renewal. Users can pay their subscriptions by clicking the payment option provided in the Invoice mail.
  2. If the subscription duration is 4 days and Reminder Notification by Email option is set as 1,2,3,4,5 and Create Renewal Order is set as 4, then the renewal order will be created 4 days before subscription renewal, then the payment reminder notification email will be sent on the 4th,3rd,2nd,1st days before subscription renewal. The remaining number of days will be neglected based upon the subscription product plan.
Manual Subscription Renewal
Charging Subscription Renewal Payments in Manual Payment
Change in Status of Subscription to Overdue in Manual Subscription Renewal
Change in status of subscription to Suspend in manual subscription renewal
Change in status of subscription to Cancelled in manual subscription renewal
Manual cancellation of the subscription by the subscriber
Manual pausing of the subscription by the subscriber
Manual resuming of the subscription by the subscriber
Expired subscription
Limit number of active subscriptions for each subscriber
Limit Number of Trials for each Subscriber
Configuring SUMO Subscription to handle Order Subscription
Manage subscriptions from admin dashboard
  1. Pending – subscription has been purchased and the initial payment is not yet received.
  2. Trial – subsciption is currently in the trial period
  3. Active – subsciption is currently active
  4. Overdue – subscription renewal payment is not made/received
  5. Cancelled – subscription has been cancelled by the subscriber/admin
  6. Suspended – subscription renewal payment is not made within the overdue duration
  7. Failed – when the user is not able to make the payment or the subscription system is not able to charge the subscription renewal payments
  8. Paused – subscription has been paused by the subscriber/admin
  9. Expired – subsciption has been expired
  1. Status
  2. Subsciption Number
  3. Order Id
  4. Subsciption Start Date
  5. Subsciption End Date
Emails sent from subscription system

Subsciption system will send emails to the user/site admin. These email templates can be found in WooCommerce -> Settings -> Emails

The List of Emails which can be Sent are

Renewal Order Settings

Go to SUMO Subscriptions -> Settings -> General -> Renewal Order Settings

Renewal Order Email Notification Settings

Go to SUMO Subscriptions -> Settings -> General -> Renewal Order Email Notification Settings

Note :

Overdue and Suspend Settings

Go to SUMO Subscriptions -> Settings -> General -> Overdue and Suspend Settings

Note: If both Overdue and Suspend Period is set as 0, then without going to Overdue and Suspend status, subscription will be Cancelled

Limit/Restriction Settings

Go to SUMO Subscriptions -> Settings -> General -> Limit/Restriction Settings

Mixed Checkout if enabled, user can purchase subscription products along with non-subscription products in a single checkout.

Limit Subscription for each Subscriber → restrict the user by

Limit Trial for each Subscriber → restrict the user by

Limit Variable subscription Products at customize where to apply the restriction for variable products. i.e. from Product Level or else from Variant Level.

Payment Gateway Settings

Go to SUMO Subscriptions -> Settings -> General -> Payment Gateway Settings

My Account Page Settings

In this section, you can allow your subscribers to use the features such as subscription pause, subscription cancel, subscription switching, etc. If you allow the features then, options will be displayed for the subscribers on their My Account Page in order to make use of the features.

Go to SUMO Subscriptions -> Settings -> My Account -> My Account Page Settings
Downloadable Products Settings

By default, for downloadable subscription products, if a subscriber subscribes for the product then when the site admin links additional files to the product, already subscribed subscribers can download the newly added files from Download section from My Account page. This behavior can be controlled.

Go to SUMO Subscriptions -> Settings -> My Account -> Downloadable Product Settings

Additional Digital Downloads Settings

You can link additional products(Downloadable Products) with Subscription Products as a Complementry to the Subscribers for Subscribing to the Product.

To Enable it, go to SUMO Subscriptions -> Settings -> My Account -> Additional Digital Downloads Settings

Synchronization Settings

Go to SUMO Subscriptions -> Settings -> Synchronization -> Synchronization Settings

Note:

  1. Prorate Payment will not be calculated if Trial is enabled for the Subscription Product.
  2. Prorate charge of the respective subscription product will be displayed in Cart Page if First Payment option is chosen as Prorate Payment on.
  3. You can customize the message for Synchronization in SUMO Subscriptions -> Settings -> Messages -> Synchronization Message Settings. Synchronization Message will be displayed after Subscription Message in SIngle Product Page which can be customized in Synchronization Plan Message field. You can use the shortcode [sumo_synchronized_next_payment_date] to display the next payment date in this field.
  4. You can customize the message for Prorate which will be displayed in Cart Page in SUMO Subscriptions -> Settings -> Messages -> Synchronization Message Settings.
  5. If you have chosen Prorate Payment on as First Recurring, then the message which is given in Prorated Amount Message during First Renewal field will be displayed in Cart Page. If you have chosen it as First Payment, then Prorated Amount Message during First Payment field will be displayed in Cart Page.
Order Subscription Settings

Go to SUMO Subscriptions -> Settings -> Order Subscription -> Order Subscription Settings

Note: Order subscription will not be applicable if the Cart contains Subscription Product or Membership Plan Access Product(from SUMO Memberships plugin).

Advanced Settings

SUMO Subscriptions -> Settings -> Advanced -> Advanced Settings

  1. Buyer purchases the subscription product, the subscription will become active once the payment is received.
  2. Payment remainder email will be sent immediately after purchasing the subscription because, the renewal order is created immediately as soon as the subscription has been purchased.
  3. This causes a confusion. If Renewal Order Delay Time is set to 10 minutes, the renewal order will be created only after 10 minutes of the subscription being purchased.
  4. The email will be sent only after the order being created.

SUMO Subscriptions -> Settings -> Advanced -> Automatic Payment Failure-Preapproval Access Revoked

SUMO Subscriptions -> Settings -> Advanced -> Automatic Payment Failure-Charging Not Successful

How to set up a Server Cron using CPanel such as HostGator

If you want to perform cron with exact timing then you can set it from your server. Steps to follow to set up real cron

  1. First disable wp-cron by adding this line define('DISABLE_WP_CRON', true); in wp-config.php
  2. Then set up the cron from your server cpanel by accessing the advanced section.
  3. Select the cron jobs and add new cron job with the time interval you are interested In
  4. Add the following command in command section of the Add New Cron Job.
    wget -q -O - http://yourwebsite.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1
  5. Change yourwebsite.com to your website domain name for the above command.
  6. Click Add New Cron Job. That’s it.
  7. Note:  If you use some security plugins, those plugins might restrict this wget command by writing mod_rewrite rule in .htaccess file. Like this RewriteCond %{HTTP_USER_AGENT} ^Wget [NC,OR] Remove this line in order to make server cron work. Please keep in mind the security implications of this change.
Hooks
  1. sumosubscriptions_active_subscription - Trigger after Subscription is Active
  2. sumosubscriptions_pause_subscription - Trigger after Subscription is Paused
  3. sumosubscriptions_cancel_subscription - Trigger after Subscription is Cancelled
  4. sumosubscriptions_admin_send_manual_subscription_email - Trigger after Admin manually send the Subscription emails
  5. sumosubscriptions_manual_{$subscription_status}_subscription - Trigger when Subscription custom status gets updated
  6. sumosubscriptions_before_adding_renewal_order_item - Trigger before adding subscription order item upon creating renewal order
  7. sumosubscriptions_before_adding_shippping_in_renewal_order - Trigger before adding shipping upon creating renewal order
  8. sumosubscriptions_before_adding_discount_in_renewal_order - Trigger before adding discount upon creating renewal order
  9. sumosubscriptions_fire_{$cron_event_name} - Trigger before Subscription Cron event gets elapsed
  10. sumosubscriptions_process_preapproval_status - Check the Automatic Subscription Preapproval status is valid to renew the Subscription
  11. sumosubscriptions_process_preapproved_payment_transaction - Automatically transact the renewal charges
  12. sumosubscriptions_preapproved_payment_transaction_success - Trigger after the Subscription renewal Success
  13. sumosubscriptions_preapproved_payment_transaction_failed - Trigger after the Subscription renewal failed
  14. sumosubscriptions_preapproved_access_is_revoked - Trigger after the Automatic renewal access is revoked by Subscriber
  15. sumosubscriptions_email_order_details - Display Subscription details table in Subscription email template
  16. sumosubscriptions_email_order_meta - Add Subscription order meta in Subscription email template
  17. sumosubscriptions_before_view_subscription_table - Trigger before View Subscription table in My Account page
  18. sumosubscriptions_after_view_subscription_table - Trigger after View Subscription table in My Account page
  19. sumosubscriptions_checkout_update_order_meta - Trigger when Subscription Order checkout is processing
  20. sumosubscriptions_after_new_subscriptions_added - Trigger after new subscriptions gets placed
  21. sumosubscriptions_before_adding_new_subscriptions - Trigger before new subscription gets placed
  22. sumosubscriptions_before_subscription_is_created - Trigger before the subscription is created
  23. sumosubscriptions_subscription_created - Trigger after the subscription is created
Filters
  1. sumosubscriptions_valid_subscription_statuses_to_become_active_subscription - Filter the Subscription statuses to become Active Subscription
  2. sumosubscriptions_subscription_failed_statuses - Get Subscription failed statuses
  3. sumosubscriptions_edit_subscription_page_readonly_mode - Bool Admin can update edit subscription page html fields.
  4. sumosubscriptions_admin_can_change_subscription_statuses - Bool Admin can update the Subscription statuses
  5. sumosubscriptions_edit_subscription_statuses - Returns Admin editable Subscription statuses
  6. sumosubscriptions_show_cron_events_post_type_ui - Bool to show Subscription cron events post type menu
  7. sumosubscriptions_my_subscriptions_table_title - Alter My Subscriptions table title in My Account page
  8. sumosubscriptions_schedule_subscription_crons - Bool whether to schedule the cron event or not
  9. sumosubscriptions_cart_product_total - Returns subscription item total in cart
  10. sumosubscriptions_add_new_subscriptions - Bool to add new subscriptions upon customer placing the subscription order
  11. sumosubscriptions_payment_mode_switcher_payment_gateways - Get valid payment gateways applicable for payment mode switcher
  12. sumosubscriptions_get_payment_mode_switcher_in_payment_gateway - Get payment mode switcher field for payment gateways
  13. sumosubscriptions_display_variation_switch_fields - Upon displaying Subscription variation switcher
  14. sumosubscriptions_multiplication_factor - Alter stripe multiplication factor
  15. sumosubscriptions_product_price_msg_for_subsc_fee - Get Subscription fee in displaying subscription plan
  16. sumosubscriptions_renewal_item_total - Alter subscription renewal order item total upon creating renewal order
  17. sumosubscriptions_alter_subscription_plan - Get Subscription plan
  18. sumosubscriptions_alter_subscription_plan_meta - Get Subscription plan meta
  19. sumosubscriptions_my_subscription_table_pause_action - Bool to show Pause button to Subscriber
  20. sumosubscriptions_my_subscription_table_cancel_action - Bool to show Cancel button to Subscriber
  21. sumosubscriptions_order_has_subscriptions - Bool to check whether the order contains subscriptions
  22. sumosubscriptions_subscription_type - Get the type of subscription based on customer checkout the subscription order
  23. sumosubscriptions_get_next_payment_date - Get the subscription next payment/due date

SUMO Subscriptions Plugin is translation ready meaning you can edit the po files by which you can translate the text to any language.

The steps to do the translation are as follows. For eg let us consider translation to French.

  1. Download and install Poedit
  2. Open the file SUMO Subscriptions-> languages folder -> sumosubscriptions-fr_FR.po using Poedit.
  3. Choose the Source text and set its corresponding French text in Translation Text Area.
  4. Save the changes.
  5. If you are using WordPress Version 3.9.13 or below, then in wp-config.php define the WPLANG as French. Syntax is define(‘WPLANG’, ‘fr_FR’);
  6. If you are using WordPress Version 4.0 or above, then go to WordPress dashboard -> Settings -> General and select the Site Language as French

SUMO Memberships

When a Subscription product is set to provide access to a Membership Plan, then the Membership Plan will be controlled by the Subscription. 

SUMO Donations

SUMO Affiliates

SUMO Reward Points

Configuring SUMO Reward Points Gateway for Renewal of SUMO Subscription products

Goto WooCommerce -> Settings -> Checkout -> SUMO Reward Points Gateway

Note: Cummulative points for Renewal Orders will be calculated based on Redeeming Conversion Settings at the time of Renewal Order creation.

1. Does it support simple subscriptions and variable subscriptions?

Yes, it supports both simple subscriptions and variable subscriptions.

2. Will the subsciption renewal be automatic?

The subscription renewal will be automatic, if the user makes payment with any Automatic Payment gateways by preapproving the future renewal payments or admin has set to Force Automatic Payment for those gateways.

3. What happens if the subscription system is not able to charge for the automatic subscription renewal?

If the subscription system is not able to charge for the subscription renwals, the status of the subscription will become Overdue.

4. What happens if the subscription revokes access to preapproval key?

If you need help please open a Support Ticket