This guide aims to teach you how to do it, explaining what features are available and options you should consider in choosing to sell products and services on an ongoing basis in your WooCommerce store.

We recommend starting with:

• Store Manager Guide, which details how to sell subscription products and services
• Renewal Process to learn how Subscriptions handles recurring payments and subscription renewals
• Adding or Changing Subscriptions and an up-to-date list of Payment Gateways that Support Automatic Recurring Payments

There is also documentation written specifically for WooCommerce developers, which details the Subscriptions API. This section includes a guide to integrating a payment gateway with Subscriptions. An advanced understanding of PHP and WordPress development is required.

Finally, an FAQ is provided to answer general questions not covered in other sections, and a Roadmap to see features planned for future releases.

Documentation Contents

• Store Manager Guide
  • Subscriptions Requirements
  • Subscription Payment Gateway Guide
  • Understanding the Subscription Renewal Process
  • Orders Related to Subscriptions
  • Understanding the Subscription Upgrade/Downgrade Process
  • How to Manually Add or Modify a Subscription
  • Subscriber’s View
  • Guide to Multiple Subscriptions
  • Subscription Status Guide
  • Migrating Subscribers to WooCommerce Subscriptions
  • Subscription Resubscribe Guide
  • Subscription Renewal Synchronization Guide
  • Subscriptions Reports
  • Subscriptions Early Renewal Guide
  • Failed Recurring Payment Retry System
  • Limited Subscription Payment Coupons
• Subscriptions FAQ
  • Differences between Subscription Products and Subscriptions
  • How Does Subscriptions Handle Staging Sites and Migrations?
  • PayPal Reference Transactions for Subscriptions FAQ
  • Testing Subscription Renewal Payments
  • Change Subscription from Automatic to Manual Payments
  • Subscriptions Scheduled Action Errors
  • Disabling Subscriptions
  • Subscriptions Logs
• Subscriptions Feature Roadmap
  • What’s New in Subscriptions 2.5
  • What’s New in Subscriptions 2.3
  • What’s New in WooCommerce Subscriptions v2.1
  • What’s New in WooCommerce Subscriptions v2.0
• Developer Documentation
  • Subscriptions Data Structure & Storage
  • Payment Gateway Integration Guide
  • Action Reference
  • Filter Reference
  • Function Reference
  • Subscription Caches
  • Subscription Product Function Reference
  • Subscriptions Management Function Reference
  • Subscription Order & Cart Function Reference

The post Introduction to WooCommerce Subscriptions first appeared on CODIBU.

If you haven’t already, you should read the Subscriptions guide for Store Managers to get a more general introduction to working with the Subscriptions extension. The information here will also be easier to understand if you have read the subscription renewal process document.

What is a Synchronized Renewal?

By default, WooCommerce Subscriptions creates the schedule for a subscription based on the day the customer signs up for the subscription. For example, if a customer buys a monthly subscription on the 15th January, she will first pay for that product on the 15th January, then on the 15th February her subscription will renew, and again on then 15th March, and so on.

However, when selling certain types of subscription products, you may find you need subscription renewal to occur on the same day for all subscribers. For example, a store selling a monthly gift box might ship the boxes on the first of each month. If a customer signed up on the 20th of January, by default her first renewal would be on the 20th of February. With renewal synchronization enabled, the customer can sign up on the 20th January and pay nothing to sign up (unless there is a sign up fee) and have the first subscription renewal processed on the 1st of February. The next renewal will then be processed on the 1st of March, then 1st April and so on.

Enabling Renewal Synchronization

The Renewal Synchronization feature is switched off by default. To enable renewal synchronization:

1. Go to: WooCommerce > Settings > Subscriptions
2. Click the Synchronize Renewals checkbox
3. Click the Save Changes button

Once the Renewal Synchronization feature is enabled, you can individually select a day on which renewals should be processed for each subscription product.

Prorating First Payment

After enabling renewal synchronization, you are presented with the option to prorate the first payment.

Prorating the first payment means the customer will be charged an initial amount based on the number of days left in the current billing period. The amount is calculated by finding the price per day for the subscription and multiplying that by the remaining number of days in the current billing period.

For example, for a $100 per year subscription that is synchronized to the 1st of January each year, if a customer signs up on the 1st July, they will be charged $50.41 at the time of signup (or $50.27 in a leap year). This is because there are 184 days between 1st July and 1st January, and the per day rate for a $100 per year subscription is $0.27397. If the customer was to sign up on the the 15th of November, they would only pay $12.87 because they would be paying for only 47 days left in the current year.

This option can apply either For Virtual Subscription Products Only or For All Subscription Products. Proration is most appropriate for virtual subscription products where the customer is buying access to a virtual good and you want to provide the customer with access to that virtual good as soon as they sign up.

Do not charge at sign-up

If the option Never (do not charge any recurring amount) is selected, no recurring amount will be charged at the time of purchase. The customer would pay on the first upcoming synchronized date. Any sign-up fees would still be charged.

Charge full amount at sign-up

If the option Never (charge the full recurring amount at sign-up) is selected, the full recurring amount will be charged at the time of purchase. There is an additional field that will appear if choosing this option called Sign-up grace period. This grace period is the number of days before the synchronized renewal day during which a subscription will not charge the recurring amount at sign-up.

This feature can be particularly helpful for physical subscription boxes. For example, suppose a store sells a subscription box that is synchronized to the first of each month. When a customer signs up for a box, you want to charge the full amount immediately to offset the cost of the box. They can choose to synchronize the subscription and charge the full recurring amount at sign-up. However, say that you also want to cut off when the current month’s box can be ordered and delivered to 15 days before the next renewal date. This would allow you to have customers ordering before about the 15th of the month pay the full amount and get a box for the current month and customers ordering after that cut-off point to not be charged until the following month and not receive a box until next month.

Creating a Synchronized Subscription Product

If a subscription product is set up to renew weekly, monthly or yearly, you can choose to align renewal schedule for that product to a specific day.

To synchronize a product’s renewal day:

1. Go to: Products > Edit Product
2. In the Product Data meta box, select a day in the Synchronize Renewals field
3. Click the Publish button to save the product.

Different Renewal Options for Different Renewal Periods

The options displayed for synchronizing subscription renewals will depend on the renewal period of the subscription product.

• For products which renew weekly, you can choose any day of the week, like Monday or Sunday.
• For products which renew monthly, you can choose a specific day of the month, from the 1st to the 27th day, or set renewals to be processed on the last day of the month, which some months will be the 28th day, some months the 30th and others the 31st.
• For products which renew yearly, you can choose a specific day of the year, like January 18th or May 22nd.

Purchasing a Synchronized Subscription

It is important to clearly communicate the subscription renewal schedule to customers so they know exactly when they will be charged for their subscription.

To communicate a synchronized billing schedule with your customers, some extra information will be presented to the customer.

The additional information includes:

• The renewal day will be specified in the subscription’s price, both on the product page and in the totals displayed on the cart and checkout pages.
• The first payment date will be displayed on the product’s page for simple subscription products (it will not be displayed for a variable subscription product as the date may be different for each variation, so the customer first needs to select a variation and add it to their cart before the date will be displayed)
• The first payment date will be displayed on the cart total on the cart page
• The first payment date will be displayed below the order total on the checkout page

Renewal Day in Subscription Price

To clearly indicate to the customer the renewal and payment schedule for a subscription, products with synchronized renewals will include the renewal day in the price.

The table below includes some examples of different prices that will be displayed to the customer for different subscriptions schedules.

First Payment Date on Cart & Checkout

To clearly indicate to the customer when the first renewal payment will be processed, the specific date of the first renewal will also be displayed on:

• the product’s page
• the cart page below the cart total
• the checkout page below the order total

If the first payment will be processed the same day the subscriber signs up for the subscription, for example, because she is signing up on a Wednesday and renewals are processed on Wednesday’s

Order Status

By default, if the order created to keep a record of the purchase a non-prorated synchronized subscription does not contain any other non-synchronized products and therefore has an order total of $0, its status will be changed to completed, regardless of whether the subscription is to a physical item or not.

This behaviour was introduced after requests by store managers who explained that the purchase of a synchronized physical item doesn’t require any products to be shipped. It a record of the customer signing up to receive the product on the sync date.

Coupons

The way coupons are applied to synchronized subscriptions is much the same as the way coupons are applied to standard subscription purchases.

The key difference is that cart, product and sign up fee coupons will only be applied if:

1. the subscription has a sign up fee; and/or
2. the subscription has a prorated payment charged at the outset;

This is because these coupons can only be applied to an initial payment. When there is no sign-up fee or prorated gap payment, these coupons can not be applied.

FAQ

When are sign up fees charged for synchronized subscriptions?

If a subscription has a sign up fee, that amount will be charged when the customer first signs up, regardless of whether the first renewal is the same day the customer signs up or not.

For example, consider a subscription that is synchronized to charge $10 on the 1st day of each month and does not include a sign up fee. If a customer signs up on the 20th January, he will pay nothing at the time of sign up. His first payment will be $10 on the 1st of February.

On the other hand, consider a subscription that is synchronized to charge $10 on the 1st day of each month and includes has a $50 sign up fee. If a customer signs up on the 20th January, he will pay $50 at the time of sign up. He will then pay $10 on the 1st of February.

Be aware that if the customer signs up on the day the subscription is synchronized to, both the sign up fee and recurring amount will be charged. For example, consider a subscription that is synchronized to charge $10 on the 1st day of each month and includes has a $10 sign up fee. If a customer signs up on the 1st of January, she will pay $20 at the time of sign up.

If the subscription’s first payment is prorated, the sign up fee will be added to the prorated initial amount.

For example, consider a prorated subscription that is synchronized to charge $30 on the 1st day of each month and does not include a sign up fee. If a customer signs up on the 20th January, he will pay $10.65 at the time of sign up – the prorated amount for the month. On the other hand, consider a prorated subscription that is synchronized to charge $30 on the 1st day of each month and includes has a $50 sign up fee. If a customer signs up on the 20th January, he will pay $60.65 at the time of sign up. He will then pay $30 on the 1st of February.

How are free trials applied to synchronized subscriptions?

If a synchronized subscription includes a free trial, the date of the first payment will be calculated from the end of the free trial period.

For example, consider a $10 / month subscription synchronized to the 1st day of each month and a 2 week free trial. If a customer signs up on the 20th January, her first renewal payment will not be charged until the 1st March because the free trial will end on the 3rd of February and the first renewal date will be calculated from that date.

If first payments are set to be prorated, no prorated amount will be charged. This would require subscriptions to have a 3-tier price to account for the initial free trial, prorated amount after the free trial and the recurring amount, which is not currently supported.

What happens if I change a subscription’s payment date?

If you or another store manager manually change the next payment date for a subscription, future payments will be processed based on the new payment date selected.

That means a subscription can be unsynchronized by changing the next payment date to a day not aligned with the synchronization schedule. For example, changing a weekly subscription synchronized to Mondays to have the next payment processed on Wednesday will mean all future payments will be processed on Wednesday. This is because future payments are calculated based on the past payment and renewal synchronization is only calculated and applied to the first payment.

If you wish to re-align the payment dates, you need to change the next payment date again after a payment has been processed out-of-sync.

What time of day are renewals scheduled to be processed?

Synchronized renewals are scheduled to run at 3:00am in your site’s timezone. You can set your site’s timezone on the WordPress General Settings administration screen.

For example, if your store is based in California, you should have your site’s timezone set to Los Angeles or UTC -7 so that renewals will be processed at the correct time.

This schedule is set only when the customer signs up. Changing your site’s timezone after a customer has signed up will not automatically change the renewal time for existing subscriptions, you may need to manually change the next payment date if some subscriptions were synchronized in the wrong timezone.

Furthermore, this applies to the first renewal only. After the first renewal, future renewals will be scheduled based on the time the last renewal was completed. For example, on the 15th January, you start selling a new monthly subscription that is synchronized to the first day of the month. You have 1,200 new subscribers sign up between 15th January and 31st January. At 3am on the 1st February, WooCommerce Subscriptions will begin processing renewals; however, it’s not possible to process all 1,200 renewals instantly, instead, Subscriptions will process them as a queue, meaning the renewal for the thousandth subscriber might not be processed until 4:00am. After it is processed, the renewal for the 1st of March will be scheduled for 4:00am, rather than 3:00am. This design helps stagger renewals on stores managing a large queue, which reduces server load.

Why does PayPal include a $0.01 trial fee for annual subscriptions?

PayPal does not allow a subscription to start on a certain date, instead, they provide a way to specify trial periods. Unfortunately, the trial must be of a certain period (i.e. day, week, month or year). This trial must also be within a maximum range, e.g. a trial period in days can be a maximum of 90 days.

If PayPal only accepted one trial period, these restrictions would make it impossible to align subscription start dates. However, they do accept two different periods. Unfortunately, PayPal only accept one free trial, the second trial period must charge an amount.

For longer subscriptions, like subscriptions that renew annually, WooCommerce Subscriptions needs to use this second trial period and therefore, tell PayPal to charge an amount for this second trial period. The minimum amount possible is $0.01, which is the amount Subscriptions tells PayPal to charge.

Unfortunately, when the date on which payments should be charged is more than 90 days from the time of sign-up, and it does not neatly fit into whole weeks or months, there is no way for Subscriptions to synchronize payments with PayPal Standard to a specific day without adding this confusing $0.01 amount to the second trial.

If you are selling annual or semi-annual subscriptions and do not want to confuse your customers with this and want to get access to other great subscription management features that are possible with more modern payment gateways, try one of the many other Payment Gateways for Subscriptions.

How are synchronization dates calculated for billing intervals greater than one?

WooCommerce Subscriptions makes it possible to choose a billing interval greater than one. For example, you can charge customers every 2nd week or every 3rd month.

The billing interval is not taken into account when determining the synchronization day.

For example, if a subscription product is synchronized to the 1st day of the month, and the interval is every 3rd month, the first renewal payment will be the first day of the next month. It will not be charged on the 1st day of the next quarter.

This is in large part because it’s not always clear what date the calculation should be calculated from.

The 1st day of the 3rd month is relatively easy. Logically, it would be calculated based on the 1st January. So for example, if a customer signs up for the above subscription on the 6th of April, their first renewal payment would be the 1st of July, not the 1st May, as it would currently be determined. But that logic does not always apply.

For example, consider a product charged every 2nd week that is sync’d to Sunday. Should it be every 2nd week from the 1st of January? Or the 1st day of the current month? Or perhaps the first day of the following month if the 2nd Sunday has already occurred this month?

Consistently using the next occuring synchornization day avoids this confusion.

If you would like for a new feature to be added to Subscriptions to take intervals into account and choose which dates to process renewals, vote for the renew on set dates Idea.

The post Subscription Renewal Synchronization Guide first appeared on CODIBU.

After a customer’s subscription has expired or been cancelled, she can create a new subscription which extends the old subscription’s terms by resubscribing from the My Account page.

Resubscribing to a subscription that ended will create a new subscription for the same product or products; but it does not have the same behavior as purchasing a new subscription, or renewing a subscription.

Resubscribing has a number of special behaviors outlined below.

Free Trials on Resubscribe

If the subscription has a free trial, the customer will not receive the free trial again when resubscribing. The customer has already benefited from the free trial when they first purchased the subscription.

Product Price Changes

If the prices for any product line items on the subscription have changed, the customer’s new subscription will be grandfathered with the original, older prices.

For example, consider a product which had a price of $10/month, but has since had a price increase to $12/month.

If the customer were to purchase the product for the first time, he would be charged $12 month. If the customer resubscribes to his expired or cancelled subscription, he will be charged $10/month.

To have subscriptions use the new price, you need to update the price on the subscription before the customer resubscribes. Prices of existing subscription can be manually modified via the Edit Subscription administration screen. To automate the price change, the AutomateWoo extension can be used to update the price.

Resubscribing with Coupons

If the original subscription has coupons applied to discount the subscription’s recurring cost, those coupons will not be automatically applied when resubscribing. Either the existing coupons, or other coupons, can still be manually applied to the resubscribe, as it uses the normal Cart -> Checkout process.

This avoids issues with applying coupons that have expired or are otherwise since been limited, for example, because their usage restriction has been reached.

It’s also a better default behavior because it’s easy enough for a customer to apply a coupon during checkout, or for a store owner to add a discount to the subscription after sign-up, but it’s harder for a store owner to remove a discount or coupon a customer has applied which the store owner didn’t intend for them to receive afterwards as it requires increasing the cost of the subscription.

To provide a coupon for resubscribing:

1. setup an automated email using AutomateWoo, Follow-ups or Jilt that is sent to the customer when their subscription expires or is cancelled.
2. include a coupon in the email – this also encourages the customer to resubscribe.

Sign-up Fees on Resubscribe

If the subscription has a sign-up fee, the customer will not be charged the sign-up fee to resubscribe to the subscription. This is because the customer has already paid the sign-up fee for the original subscription.

The exception to this is when the subscription has a $0 recurring total. Subscriptions assumes you are shipping physical products on a different schedule to the payment schedule and using the sign-up fee to charge the full amount of the subscription up front.

Billing Schedule after Resubscribing

If a subscription is cancelled or expired, the billing schedule for the new subscription is based on the date the customer resubscribes.

For example, a customer has a $10/month subscription renewing on the 1st of the month and it expires after 6 months. If the customer waits until the 5th to resubscribe to the subscription, the next renewal will be processed on the 5th of the following month, and each renewal after that will be processed on the 5th.

Billing Schedule for Subscriptions Pending Cancellation

If the subscription’s status is pending cancellation, the billing schedule for the new subscription is based on the pre-paid term of the existing subscription.

For example, a customer has a $10/month subscription renewing on the 1st of the month. If they cancel on 15th of the month, the subscription will have the pending cancellation status until the 1st of the next month, which is the end of their pre-paid term.

If the customer waits until the 25th of the month to resubscribe to the subscription, the next renewal will be processed on the 1st day of the following month as that is the end of the prepaid term. Each renewal after that will also be processed on the 1st.

If a customer subscribes, cancels, and then decides to resubscribe before the next recurring payment, this doesn’t change the billing schedule.

For example, a customer has a subscription that renews on the 1st of every month. They decide to cancel on 15 July. This will set their subscription status to pending-cancellation. This means they are still a subscriber with full benefits until the next recurring period, and when that period comes they won’t be charged and their subscription moves fully to cancelled. But let’s imagine on the 20th they decide to resubscribe. Their next recurring payment would be on the 1st of August.

Further Reading

The subscription resubscribe process is part of a larger renewal process in WooCommerce Subscriptions. The renewal process is documented in detail in the Subscription Renewal Guide. Much of the information in that guide is relevant for understanding renewals.

To learn more about how the old and new subscription are related to the order created to record the resubscribe, refer to the section in the Subscription Orders document on Resubscribe Orders.

To understand what the resubscribe process looks like from your customers’ perspective, refer to the Subscribers View > Resubscribe document.

If you have a question not answered here, such as “How to remove the Resubscribe button from the My Account page?” take a look at the Subscriptions FAQ.

The post Subscription Resubscribe Guide first appeared on CODIBU.

If you haven’t already, you should read the Subscriptions Guide for Store Managers before continuing. The information here will also be easier to understand if you have read the Guides on the subscription renewal process, subscription switching and WooCommerce orders.

Subscriptions vs. Orders

Before understanding the ways an order can be related to a subscription, it’s important to understand the purpose and data on a subscription and compare that with an order, to see how the two are similar and how they differ.

Subscriptions are an extension of orders. A subscription has all the same data as an order, including a:

• customer
• status
• payment method
• billing & shipping address
• product, fee, tax and shipping line items.

However, a subscription also has data an order does not have, including:

• recurring billing period and interval
• next payment, trial end and start date
• related orders.

The reason subscription data includes all order data is because of the similarities in the purpose of the two items. Specifically, an order is a record of a transaction in the past. A subscription is an agreement for transactions in the future.

The reason orders are linked to a subscription is because a subscription can have transactions in the past. These transactions may have:

1. created the subscription
2. been part of the subscription’s renewal billing terms; or
3. changed the subscription, for example by upgrading a product on it.

Because of this, a subscription can have multiple orders associated with it to record different historical transactions during its life-cycle. An order can also be associated with one transaction that relates to multiple subscriptions.

Subscription Order Types

A subscription can have a range of orders linked to it, including:

• Renewal orders
• Resubscribe orders
• Switch orders
• Parent order

Each of these order types are the same as an order created to track a purchase via the normal WooCommerce checkout process. The key difference is that the order is linked to a subscription via a special relationship to track part of that subscriptions life-cycle.

These relationships are also not unique. For example, a Resubscribe Order can also be a Parent Order because a new subscription is created when resubscribing to an expired or cancelled subscription.

Parent Orders

The parent order for a subscription records the creation of the subscription. Normally, this is a record of a subscription product being purchased via the WooCommerce checkout process.

When a customer adds a subscription product to the cart, and then completes the checkout process to pay for that product, an order is created to record that payment. A subscription is also created to manage the future payments agreed to when purchasing that product. That order becomes the subscription’s Parent Order.

Parent Orders are usually only created via checkout. However, they can also be created via the Add/Edit Subscription administration screen, or import tools when migrating subscriptions to WooCommerce.

Importantly, a subscription can only ever have one Parent Order. A subscription can only ever be created once, so it only needs one Parent Order to record that transaction. On the other hand, one Parent Order can be related to multiple subscriptions, because it’s possible to purchase different subscription products in the same transaction.

As subscriptions are not necessarily created via a transaction, a subscription will not always have a Parent Order. For example, subscriptions created via the Add Subscription administration screen will not have a Parent Order unless such an order is also manually created.

Renewal Orders

A key part of a subscription are its recurring payments. Each recurring payment is recorded in a Renewal Order during the subscription renewal process.

Renewal Orders are normally created automatically on the subscription’s predefined billing schedule. They can be used to record either an automatic or manual recurring payment. Or no payment at all, in the case of subscriptions with a $0 total.

Renewal Orders can also be manually created via the Edit Subscription administration screen.

Importantly, a subscription can have multiple Renewal Orders associated with it, as multiple recurring payments may have been processed during its life-cycle. For example, a monthly subscription that has been active for 12 months will have 11 Renewal Orders.

A Renewal Order can also be associated with multiple subscriptions. This makes it possible to batch process recurring payments for different subscriptions. This feature isn’t built into WooCommerce Subscriptions, but it is possible with underlying design.

Resubscribe Orders

If a customer wants to extend an expired subscription, or resume a previously cancelled subscription, she can resubscribe to the subscription on the My Account > View Subscription page.

The resubscribe process takes the customer through the normal cart and checkout flow to complete sign-up on the subscription. As part of this flow, an order is created to record the transaction. This order is both a Resubscribe Order, as it records the resubscribe action, and a Parent Order, as a new subscription is created to continue the old subscription’s terms.

A Resubscribe Order is linked to both the old subscription which is being resubscribed to, and the new subscription being created to continue the old subscriptions terms. This means a subscription can have up to two Resubscribe Orders associated with it – one to record its creation, if it was created by resubscribing to another subscription, and one to record a new subscription created from its terms after it expired or was cancelled.

Switch Orders

When a customer upgrades or downgrades their subscription, the switch process takes the customer through the normal cart and checkout flow to complete the transaction.

As part of this flow, an order is created to record the upgrade or downgrade transaction. As this order records the switch transaction, it is linked to the subscription using a relationship referred to as a Switch Order.

In some cases, the Switch Order will also be a Parent Order, as when the new subscription’s schedule does not align to existing products on the existing subscription, a new subscription will be created.

Importantly, a subscription can have multiple Switch Orders associated with it, as a customer can upgrade or downgrade the same subscription multiple times in different transactions.

FAQ

Why are some orders in the related orders table not linking to the order?

In the related orders table on the Edit subscription screen, there might be some orders that do not link to an edit order screen. This can occur if the order was in the subscription’s list of known related orders but was unable to be loaded correctly.

Orders which cannot be loaded have either been deleted from the database or have corrupt data. To preserve the order history, the order ID that the subscription has a record of will be displayed – even if all the data cannot be displayed.

The post Subscription Orders first appeared on CODIBU.

This guide details each status, explains when it is applied and what it represents.

Pending Subscription Status

When a subscription is first created, either by a customer purchasing a subscription product via checkout or a store owner manually adding a subscription, it will have the Pending status.

This status indicates that the subscription has been created, but no payments have been processed on the subscription.

Active Subscription Status

After the initial payment for a subscription has been processed (if any payment is required), it will be transitioned to the Active status.

This status indicates the subscription will renew or expire at a given time in the future. When a subscription is Active, the user associated with the subscription will be assigned the default subscriber role, and may be given special access by other extensions, like WooCommerce Memberships. Whenever a subscription is activated, Subscriptions will also calculate the next payment date for the subscription if it’s not already set.

On-Hold Subscription Status

A subscription is placed On-Hold when an associated order is awaiting payment, or it has been manually suspended by the store owner or customer.

A subscription can remain On-Hold indefinitely. If it was manually suspended, it will need to be manually reactivated. If it was suspended awaiting payment, it will be reactivated once that payment is processed.

When a subscription is On-Hold, the user associated with the subscription will be assigned the default inactive role, and may no longer be granted special access by other extensions, like WooCommerce Memberships.

Pending-Cancellation Subscription Status

When a subscription is manually cancelled by the customer, its status is not usually transitioned to Cancelled immediately. If the subscription has a pre-paid term that has not been provided yet, the subscription will be assigned the Pending Cancellation status.

During this time, the user associated with the subscription will continue to have the subscriber role, and may be given special access by other extensions, like WooCommerce Memberships.

When the pre-paid term ends, the subscription’s status will be transitioned to Cancelled.

Cancelled Subscription Status

The Cancelled status is assigned to subscriptions with the Pending Cancellation status when they reach the end of their pre-paid term.

When a subscription is Cancelled, the user associated with the subscription will be assigned the default inactive role, and may no longer be granted special access by other extensions, like WooCommerce Memberships.

Expired Subscription Status

If an end date is set on a subscription, either because the product it relates to has a defined subscription length, or because the end date was manually set on the subscription, when that date is reached, the subscription will be assigned the Expired status.

When a subscription expires, the user associated with the subscription will be assigned the default inactive role, and may no longer be granted special access by other extensions, like WooCommerce Memberships.

Switched Subscription Status

This is an old status used in WooCommerce Subscriptions versions prior to 2.0. It was assigned to a subscription after the subscription was upgraded or downgraded.

Because individual items on a subscription can now be switched, this status is no longer necessary or used.

The post Subscription Status Guide first appeared on CODIBU.

This system can help recover revenue otherwise lost due to payment methods being temporarily declined. For example, if a credit card balance was at its limit when attempting the first recurring payment and the charge was declined, it can be successfully processed a few days later when the card owner has paid off the balance.

This guide provides an overview of the Failed Payment Retry system and is intended to provide non-technical details for store managers. For a technical overview, refer to the Developer Guide to the Failed Payment Retry System.

Enabling the Retry System

The retry system is disabled by default. To enable it:

1. Go to: WooCommerce > Settings > Subscriptions settings administration screen.
2. Scroll to the Miscellaneous settings section.
3. Tick the Enable Automatic Retry checkbox.

Subscriptions will now automatically retry payments that fail when certain requirements are met.

Retry System Requirements

Subscriptions does not retry all failed recurring payments. It only retries a payment for a subscription that uses:

• Automatic recurring payments; and
• A payment gateway that does not control the billing schedule for the subscription

Failed payments for subscriptions using PayPal Standard cannot be retried automatically, as the payment gateway does not allow it.

Failed Recurring Payment Retry Process

The retry system works by applying a set of retry rules whenever a renewal payment fails. The full set of retry rules defines the specific behavior of the retry process between the first failure and finally declaring the payment as failed and no longer attempting to process the payment.

The general retry process proceeds like this:

1. Automatic recurring payment fails.
2. Subscriptions checks if a retry rule exists for this specific payment failure.
3. If a rule exists, it is applied and Subscriptions will:
   • schedule a pending retry event to occur after a set period of time
   • set the status on the subscription to match the status defined by the rule
   • set the status on the order to match the status defined by the rule
   • email the customer the email defined by the rule
   • email store managers the email defined by the rule
4. When the scheduled time for the retry event arrives, Subscriptions will retry the payment if:
   • the retry still has a status of pending
   • the order still requires payment
   • status on the subscription matches the status defined by the rule previously applied
   • status on the order matches the status defined by the rule previously applied
5. If the payment fails on this retry attempt, steps 2 through 4 are repeated until there are no more retry rules.

If no rule exists, either because the all retry rules have been exhausted or the retry system cannot be applied to the renewal order, the renewal order is marked failed and the customer is sent the Customer Renewal Invoice email (if enabled), per the normal failed renewal payment process.

Retry Statuses

A record of the retry is stored in the database when a retry rule is applied after failed payment. This retry will be stored with the status of Pending.

When the scheduled retry time arrives and Subscriptions starts the retry process, it sets the stored retry status to:

• Processing if the order still needs payment and the order and subscription have the status defined by the retry rule. This status signifies that Subscriptions has begun to process the retry attempt.
• Canceled if the order no longer requires payment, or the order or subscription has a status other than a status defined by the retry rule. This signifies that the payment no longer needs to be retried.

If the payment is attempted again, after the payment gateway has finished processing the attempt, the stored retry’s status will be updated to:

• Complete if payment was successfully processed for the order; or
• Failed if the renewal order still needs payment

Retry Rules

Subscriptions uses a set of Retry Rules to control the schedule and behavior of each retry attempt.

Each retry rule defines the:

• Interval: Amount of wait time between the time of failed payment and retry attempt.
• Customer Email: Email to send the customer about failed payment (optional – to avoid emailing customer about all failed payments). This email is sent when the payment attempt fails, not when it is retried.
• Store Owner Email: Email to send the store owners at defined email addresses about failed payment (optional).
• Order Status: Status applied to the renewal order for the period between the time of failed payment and retry attempt.
• Subscription Status: Status applied to the subscription for the period between the time of failed payment and retry attempt.

Subscriptions provides a default set of rules, but these rules can also be customized with code discussed in the Developer Guide to the Failed Payment Retry System.

Default Retry Rules

Subscriptions applies five (5) default retry rules to retry failed payments over 7 days by default.

Retry Rule 0:

• Interval: Subscriptions waits 12 hours between failed payment and first retry attempt.
• Customer Email: No email is sent to the customer.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

Retry Rule 1:

• Interval: Subscriptions waits another 12 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

Retry Rule 2

• Interval: Subscriptions waits another 24 hours between failed payment and retry attempt.
• Customer Email: No email is sent to the customer.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

Retry Rule 3:

• Interval: Subscriptions waits 48 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

Retry Rule 4:

• Interval: Subscriptions waits 72 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

After the fifth retry is processed, the renewal order is marked Failed and the customer is sent the Customer Renewal Invoice email (if enabled), per the normal failed renewal payment process.

Monitoring Failed Payment Retries

To help you track automatic failed payment retries, Subscriptions displays retry information in a different places throughout the WooCommerce administration area.

Retry Date on Edit Subscription Screen

If a subscription is currently within the retry process, it should have a Pending retry date set. This date is displayed at WooCommerce > Edit Subscription.

To view this date:

1. Go to WooCommerce > Edit Subscription for a subscription with a failed payment pending retry.
2. Find the Renewal Payment Retry date in the Billing Schedule meta box.

Automatic Failed Payment Retries Meta box

The retry history for a given failed payment is displayed in the Automatic Failed Payment Retries meta box. This metabox is added to Edit Order for renewal orders with retries. It is only displayed on orders with failed payments.

To view the retry history for a renewal order:

1. Go to WooCommerce > Edit Order for an order with a failed payment.
2. Find the Automatic Failed Payment Retries meta box toward the bottom of the screen.

 

Subscription Relationship Column of the Orders Table

If an order has failed payment retries, an additional clock icon is displayed in the Subscription Relationship column of WooCommerce > Orders. A tooltip on this icon displays number of retries of each status associated with the order.

To view the retries for an order:

1. Go to WooCommerce > Orders
2. Find an order with the clock icon in the Subscription Relationship column.
3. Hover the mouse cursor over the clock icon to reveal the tooltip.

 

Failed Payment Retry Report

An overview of your entire store’s failed payment retries is also available in the Failed Payment Retry Report.

This report allows you to view revenue recovered by the failed payment retry system and the average number of retry attempts before successfully processing payments in a given time period.

Retry Emails (Dunning)

The retry system can email the customer and/or store owner to notify them of the failed payment and scheduled retry. This makes it possible to implement a dunning process for failed payments.

When defined in the retry rules, emails will be sent when a payment attempt fails, not when the payment is retried. This makes it possible to:

• notify the customer that the payment attempt failed immediately;
• inform them when it will be retried (if at all); and
• provide a link to manually complete the the payment before it is automatically retried, in case the customer knows it will continue to fail due to an expired credit card number or similar.

Subscriptions provides two default email templates — one for emailing customers; and the other for store owners. Both email templates use the WooCommerce Email system, which means they can be enabled or disabled and customized the same way as other WooCommerce emails.

 

Manually Retry a Failed Recurring Payment

In addition to the automatic retry system, Subscriptions provides a method for store managers to retry a failed recurring payment.

To manually retry a failed payment:

1. Go to the WooCommerce > Edit Order screen.
2. Click Actions.
3. Click Retry Renewal Payment.
4. Click Save Order.

 

Retry Renewal Payment Action Requirements

For this action to be displayed, these requirements must be met:

• Order must be a renewal (action is not displayed on initial orders or non-subscription orders)
• Order total must be greater than zero
• Order must have a Payment Method set
• Payment method must support payment date modifications
• Subscription must require automatic payments, not manual renewals
• Order status must be Failed or the status set by the last retry rule

FAQ

Why isn’t the customer emailed when the first payment fails?

The first retry is designed to address any temporary technical issues that don’t need or require the customer’s involvement to fix. Because of of this, the first retry attempt happens 12 hours after the first payment.

This short timeframe doesn’t give the customer much time to log in and fix any issues, such as paying off a credit card balance. The retry system is also unsure after first failure that the issue can be addressed by the customer, as it may be other factors. Because of this, the customer is not yet contacted.

For example, if a payment fails at 6:00 pm on Wednesday night. At 6:00 am Thursday morning, the payment will be retried. If that retry fails, then the customer is emailed. If the customer was emailed at 6:00 pm Wednesday night, it’s unlikely they’d seen the email until after payment was retried at 6:00 am Thursday morning. They’d check their inbox at 9:00 am Thursday morning and find two emails.

How is the next renewal payment date calculated after a successful retry?

The automatic retry system does not change default behavior for calculating next renewal payment date.

For most subscriptions, the next payment date is calculated based on the date the payment is successfully processed by the retry system. For example, consider a monthly subscription product purchased on 1st of February. If the automatic renewal payment fails on 1st of March but is not successfully processed by the automatic retry system until 3rd of March, the next payment date is calculated as 3rd of April, not the 1st of April.

The exception to this is when the subscription contains a synchronized subscription product. If the subscription is synchronized, the next renewal pay date is calculated from the original renewal date, not the date the payment is processed. This ensures synchronized dates are preserved even when payment is late.

If you want the next payment date to always be calculated from the last scheduled payment date, install WooCommerce Subscriptions – Preserve Billing Schedule.

Can a customer log in and change credit card details for a renewal that is currently pending retry?

Yes. A customer can pay for a failed renewal order egithub.com/…/woocommerce-subscriptions-preserve-billing-scheduleven when its payment is pending automatic retry. Paying for the renewal order manually will also update the payment method used on the subscription.

By default, the email sent to the customer to notify them of the failed payment and pending retry also includes a call to action and link to login and manually pay for the order to encourage them to do so.

The post Failed Recurring Payment Retry System first appeared on CODIBU.

This guide provides an overview of the Subscriptions Reports feature. It is intended to provide store managers with non-technical details about reports, details how the report derives insight, and why the report is useful.

Viewing Reports

To view the Subscriptions Reports:

1. Go to WooCommerce > Reports.
2. Click the Subscriptions tab.
3. Click the name of the report you wish to view from the list.

Subscription Events by Date Report

The Subscription Events by Date report displays aggregated data for the most important events that occur during the lifecycle of your subscriptions, like sign-ups, renewals and cancellations. This data can be displayed over a number of predefined durations, like current year, current month, last month or last 7 days. They can also be displayed over a custom date range.

The following data is displayed in the Subscription Events by Date report:

• Sign-up Revenue: the total value for orders placed to purchase subscription products during the period (subscription parent orders). The order totals can include sign-up fees, recurring amounts charged at sign-up, as well as amounts for other items, fees, taxes and shipping. Only orders with a paid status, like processing, completed or on-hold, are taken into account.
• Renewal Revenue: the total value of automatic or manual renewal orders created for subscriptions. The order totals can include fees, taxes and shipping. Only orders with a paid status, like processing, completed or on-hold, are taken into account.
• Resubscribe Revenue: the total value for orders placed to resubscribe to existing subscriptions during the period. The order totals can include other items, fees, taxes and shipping. Only orders with a paid status, like processing, completed or on-hold, are taken into account.
• New Subscription: the number of new subscriptions created during this period, either by being manually created by a store manager, bulk imported or a customer placing an order via the store.
• Subscription Signups: the number of new subscriptions created during this period by customers placing an order in the store, which now have a paid order status. This does not include subscriptions manually created by a store manager.
• Subscription Resubscribes: the number of resubscribe orders created during this period by customers placing an order in the store, which now have a paid order status.
• Subscription Renewals: the number of automatic or manual renewal orders created for a subscription with a paid status, like processing, completed or on-hold.
• Subscription Switches: the number of upgrade, downgrade or cross-grade events recorded by a customer placing an order in the store. Only orders with a paid order status are taken into account.
• Subscription Cancellations: the number of subscriptions cancelled by the customer or store manager. The subscriptions may not have actually ended yet, as the pre-paid term may continue into the future, which is why the cancellation count may differ to the ended count.
• Subscription Ended: the number of subscriptions which have either the expired or cancelled status.
• Current Subscriptions: the number of subscriptions that have not ended for the given period. This is all subscriptions with an end date after the current period’s date and a status other than pending or trashed. For example, if a chart shows 3 periods: January 1st, 2nd and 3rd, and the store has 10 subscriptions on the 1st of January with status of active, then 5 of those end on the 3rd of January, there will be 10 Current Subscriptions on the 1st and 2nd January and 5 on the 3rd of January. The number shown in the report’s legend is the total at the end of the chart’s period.
• Net Gain/Loss: the difference between the unended subscriptions at the start and end of a given period. This provides a measure for your store’s churn.

This report makes it possible to review historical trends across many different metrics for the subscription component of the store.

Upcoming Recurring Revenue Report

The Upcoming Recurring Revenue report provides a basic forecast for your subscription revenue.

The report determines the number of renewal events that will occur during a given period of time in the future. It does this by looking at the next payment date, billing period and interval for each of your active subscriptions and determining how many payments will occur before the end of the report’s duration, or the subscription’s end date, whichever comes first.

It’s important to note that:

• only currently active subscriptions are used in these calculations, no attempt is made to forecast new sign-ups based on the store’s growth rate;
• the calculations assume all scheduled future payments will be processed without failure; and
• the calculations assume that the subscription will not be cancelled or suspended to prevent any scheduled payments being processed.

For these reasons, the upcoming recurring revenue forecasts should be treated as a guide only and not used as the basis for important business decisions.

Retention Rate Report

Retention is the foundation of growth; without keeping your existing users, you’re always filling a leaky bucket.

The Subscription Events by Date report displays churn over time. However, it does not provide any insight into the average length of your subscriptions.

The Retention Rate report fills this gap by displaying the current lifespan for the subscriptions in your store.

This report is very helpful for revealing hotspots for churn. For example, you may see a large drop after 6 months. Identifying these churn hotspots makes it possible to proactively address them. For example, an email could be sent during the 5th month before that 6 month drop to open a conversation with subscribers before they decide to cancel.

Unlike other Subscription reports, the Retention Rate report does not provide a way to customise the timespan. Instead, it will always use the entire lifetime of all subscriptions in your store.

Subscription Lifespan

The lifespan for a subscription is the total time between when it is first created and when it ends, either by cancellation or expiration. Subscriptions doesn’t take into consideration how long the subscription is active or on-hold during these two points. It does not record that data.

For example, a subscription that is created on 1st January 2016 and expires on 1st January 2017 has a lifespan of 12 months, regardless of whether it is on-hold for some of those months.

The lifespan also accounts for how the subscription ended. If the subscription was canceled, the cancellation date is used as the end of its lifespan. This is usually before the subscription’s actual end date, but it is a more accurate representation of retention, as it indicates when the customer decided to end the subscription, not when the prepaid term came to an end.

For example, an annual subscription created on 1st January 2016 and cancelled on 2nd July has a lifespan of 6 months, even though the end date is 1st January 2017, the end of the prepaid term.

Retention Period for X-Axis

The period used to plot the lifespan of your subscriptions on the x-axis depends on the length of the longest subscription lifespan in your store.

If any subscription in your store has a lifespan over one year, the chart will plot retention by month. If a subscription has a lifespan of more than 6 months but not more than a year, it will plot it using weeks, otherwise, it will use days.

Unended Base Point

The Retention Rate chart uses the number of subscriptions that have not yet ended as the base point for the y-axis, rather than a 0 base. This helps to exaggerate changes in the chart.

Subscriptions by Product Report

The Subscriptions by Product report provides an overview of the popularity and revenue for your subscription products and subscription product variations. Specifically, this report details:

• Subscription Counts by Product: Number of subscriptions that include this product as a line item and have a status other than pending or trashed.
• Average Recurring Line Total by Product: Average line total for this product on each subscription.
• Average Lifetime Value for each Product: Average line total for this product line item across subscription orders. This is determined by combining the line total for this product on both renewal and initial orders then dividing by the total number of non-pending subscriptions for that product.

Revenue from subscription products is based on the line total for each product on each order: both sign-up orders and renewal orders. It does not include shipping, fees or other amounts recorded in order totals.

Subscription product variations are also included in the ‘Subscription Product’ column. Variations can be identified by a leading hyphen and will be located directly below the corresponding parent product.

Subscriptions by Customer Report

The Subscriptions by Customer report provides an overview of your most loyal and valuable customers.

This report provides a breakdown of:

• Active Subscriptions: Number of subscriptions this customer has with a status of active or pending cancellation.
• Total Subscriptions: Number of subscriptions this customer has with a status other than pending or trashed.
• Total Subscription Orders: Number of signup, switch and renewal orders this customer placed at your store with a paid status (i.e. processing or complete).
• Average Lifetime Value: Total value of this customer’s signup, switch and renewal orders. This includes fees, tax and shipping line items on those orders.

Failed Payment Retries Report

The Failed Payment Retries report provides an overview of the attempts to automatically retry recurring payments that previously failed via the Subscriptions’ Retry System.

This report details:

• Recovered Renewal Revenue: Total revenue, including tax and shipping, recovered with the failed payment retry system by successfully processing payment on a renewal order that previously failed.
• Renewal Orders: Number of renewal orders with a failed payment and then managed by the retry system to attempt to recover revenue for this order.
• Successful Retry Attempts: Number of retry attempts to process a payment that previously failed.
• Failed Retry Attempts: Number of retry attempts for this period that did not result in successful payment. Default retry rules include 5 retry attempts for each failed payment, so it is common for this number to be larger than the number of renewal orders and successful retry attempts.
• Pending Retry Attempts: Number of retry attempts not yet processed. For any pending retries to be displayed in this report, you need to choose a custom date range and include a date in the future as pending retries are only ever in the future.

WooCommerce Status Widget

In addition to data on the WooCommerce > Reports administration screens, Subscriptions also adds data about subscription related events to the WooCommerce Status widget on the main WordPress Dashboard.

Data in this widget includes the following for current calendar month:

• Signup count: New subscriptions purchased by customers placing an order in the store.
• Renewal count: Number of manual and automatic renewal orders created and currently with the status of completed, processing, on-hold or refunded.

FAQ

How is report data cached?

Report data is cached to speed up the load time of the Reports. Report data is cached in the background to avoid slowing down page load times for your customers or other administrators. These requests are initiated via WordPress’s Cron system. When and exactly how the report data is cached depends on the size of your site’s database.

On small sites with less than 3,000 subscriptions and 25,000 orders, the process to update the cache for report data is scheduled to be 5 minutes after any event that would invalidate the existing cache. The update process for each report is then separated 5 minutes to avoid running the resource intensive queries on your site’s database at the same time. This means the cache of report data may fall out-of-sync by up to 30 minutes with the site’s current data.

On sites with more than 3,000 subscriptions or 25,000 orders, the cache is only updated once per day. This update begins at 4am in your site’s timezone. The cache update process for each report is separated 15 minutes to avoid running all the resource intensive queries on your site’s database, which can potentially lead to the database being inaccessible via other requests. This means report data may be as much as 24 hours out-of-date on larger sites.

If your site is using the later method, a notice indicating this will be displayed at the top of the Report page.

How can I disable report cache updates?

On larger sites with over a hundred thousand rows in the posts table, which generally means over 100,000 orders, subscriptions or other WordPress post types, like blog posts or pages, the report queries may lead to MySQL errors, often seen by 502 Bad Gateway HTTP errors.

To avoid these errors without having to fine tune MySQL, you can disable report cache updates using the free plugin here. This prevents the queries running automatically in the background to update the report data. The database queries will still run when loading the Reports page to generate the data.

These queries will be rewritten once WooCommerce and Subscriptions move to custom database tables to avoid having issues until having much larger databases.

What is a “cache invalidating” event?

Cache updates are only run after a cache invalidating event. These are events which add, remove or modify some piece of data that is included in a report.

The events which invalidate the cache vary depending on the report. Example events are a new renewal payment, subscription status change or subscription upgrade/downgrade.

Why do reports on custom time periods load more slowly than default time periods?

When loading reports for pre-defined time periods, like Last Month, cached data is used. However, when loading reports for customer time periods, like 18th January to 13th November, the report data must be generated. It is not feasible to cache report data for all possible time periods. This means viewing a report for a custom time period will often be slower than viewing a report for a pre-defined period.

How do I get more advanced reporting?

To get access to additional reports or more fine grained control over reports, there are two options:

1. Use Metorik reports for WooCommerce Subscriptions. Connecting your store to Metorik provides reports for historical data, not just events which occur after connecting to Metorik.
2. Request the new reports or modifications to existing reports via the WooCommerce Subscriptions Ideas Board. Features that get over 200 votes are added to the roadmap.

The post Subscription Reports first appeared on CODIBU.

Step 1. Before Updating

To help prevent any issues when updating your live site, there are some important things to know and steps you can take before updating.

WooCommerce Dependency

Major new versions often increment the minimum WooCommerce version requirements.

For example, Subscriptions v2.0 requires a minimum of WooCommerce 2.3 and Subscriptions v2.1 requires WooCommerce 2.4 or newer. You cannot use Subscriptions with a version of WooCommerce that does not meet the dependency.

The first step before updating Subscriptions therefore is always to check your version of WooCommerce. If you are running a version of WooCommerce that is no longer supported by the new version of Subscriptions, please update WooCommerce before updating Subscriptions. However, be aware that this only applies if you have kept your extensions mostly up-to-date. If you are upgrading Subscriptions and/or WooCommerce a year or more late, then you will need to do version juggling to make sure you have compatible versions running. For more information on this, see the section on version upgrade paths below.

Update Other Plugins Too

On occasion, major new versions of Subscriptions, like version 2.0, introduce breaking changes with prior versions. This means extensions that integrated with Subscriptions may have had to update compatibility for the new version. To get access to this updated compatibility, you will need to be running the latest version of these extensions so please update all of your site’s other plugins, especially WooCommerce extensions, before updating Subscriptions.

Create a Backup

Before updating Subscriptions to any major new version, you should back up your site’s files and database. This is especially important for major versions like 2.0 or 3.0 where data storage is often updated.

There are a couple of services out there that make backups easier for you:

• BackupBuddy is a very popular backup and migration tool amongst our customers.
• ManageWP does a lot more and is especially useful if you manage multiple websites.
• VaultPress is the full backup service by Automattic.

You can also perform backups manually, but making backups and ensuring your website continues to function are extremely important.

Once you run the upgrade process to convert your database to newer versions of Subscriptions, there is no undo button. The only way you can restore the old data is by restoring your site from a backup. This is why it is important to make a backup before updating the extension.

Step 2. Create a Staging Site

Now that you have updated all the plugins on your live site and created a backup of your site, you should test the new version of Subscriptions on a staging site before upgrading on your live site.

Many WordPress hosts offer a simple way to create staging sites, including:

• Site Ground
• Page.ly (SkyVerge published a great guide on how to create a staging site with Page.ly)
• WP Engine

If you are unsure of whether your host provides staging sites, contact your hosting company’s support team to ask.

If your host does not offer a staging site feature, there are premium tools available to help. The WP Stage Coach plugin is a great way to create a staging site without having to copy databases and files manually. Alternatively, you can manually create a staging site by following one of the many tutorials online, like this tutorial from Maintainn or this one from WP Beginner.

Subscriptions is designed to handle staging sites safely. No subscription related emails or recurring payments will be processed from your staging site once it has been set up (unless you enable them).

Step 3. Test Subscriptions on Staging

Now that we have a test environment with all the files and database from our live website, including its products, orders, and subscriptions, we can test the Subscriptions upgrade process on that site. Once it is upgraded, we can look at a few pages and run through a few common processes to make sure they are working correctly.

Once we have tested the changes on the staging site, we can confidently repeat the same steps on the live site.

Step 3.1. Install the Latest Version of Subscriptions

To install the latest version of Subscriptions:

1. Go to your WooCommerce.com > My Account > Downloads page
2. Click Download next to WooCommerce Subscriptions
3. Go to the WordPress Administration dashboard on your staging site (e.g. www.example.com/wp-admin/)
4. Uninstall the active version of Subscriptions plugin by following the instructions for manually uninstalling a WordPress plugin
5. Install the plugin with the zip file you downloaded from WooCommerce.com by following the instructions for manually installing a WordPress plugin

Step 3.2. Run the Upgrade Process

Some new versions of Subscriptions, like version 2.0, require changing the way data is stored in your site’s database. In order to do this, Subscriptions will provide a database upgrade process.

Once the new version of WooCommerce Subscriptions has been activated, if it needs to upgrade your database, you will be redirected to the upgrade process page. Subscriptions will redirect all administrative users to this page to ensure that the database is upgraded as soon as possible when database upgrades are required. Once you arrive at the upgrade process page, begin the upgrade by clicking Upgrade Database.

The upgrader will process small batches of subscriptions until all subscriptions have been upgraded. Leave the upgrader webpage open until the upgrade completes.

Subscriptions will provide you with estimated length of time until the process will be completed. If the upgrade process is estimated to take a long time, you can leave the computer or continue to work from other tabs or windows; however, do not close the webpage where the upgrade process is running. The webpage needs to remain open for the upgrade to continue.

If you do happen to close the webpage, you can reload your website and resume the process without any issues. Similarly, if an error occurs during the upgrade process, refresh the page and resume the upgrade. Then contact support after the upgrade has completed successfully. The upgrade process is designed to handle many errors and it can often continue without corrupting your data if something goes wrong.

If the upgrade process is unable to complete, create a support ticket so that we can help diagnose the issue as soon as possible. Be sure to include the log file mentioned below (upload it to a free service like CloudUp, CloudApp or Dropbox and include the link).

Upgrade Logs

Subscriptions keeps a log of everything it upgrades during the process. If you need to contact support about issues with the upgrade, please include this file with the support ticket. It can be found under the file path: /wp-content/uploads/wc-logs/ in the log file beginning with wcs-upgrade.

This log file will automatically be deleted a few weeks after the upgrade has completed successfully.

Upgrade Process Design

The batch size for each upgrade will be between 35 and 50, depending on the number of subscriptions on your site (the more subscriptions the smaller the batch size). By upgrading the data in small batches, the upgrade process is slower than doing one large database query or processing larger batches, but it is also more reliable. Specifically, small batches prevent timeout or memory exhaustion errors on the many varieties of possible server configurations.

Because upgrading small batches can be slow, the upgrade process is written is such a way that only administrative users are blocked from accessing the store while the upgrading is in progress. Customers, non-logged in visitors and other non-administrative users on your site can continue to browse and even purchase products (including subscription products) from your store while the upgrade is in progress.

Step 3.3. Test, Test, Test

Once the upgrade process completes, you will be redirected to a welcome page providing an overview of the new features in this version of Subscriptions. You can use links on this page to navigate to pages on your site to test out new and existing Subscriptions features.

Because major new versions of Subscriptions often introduce a number of changes and new features, it’s important to test as many things as possible before you start using it on your live website. We test new versions for months on multiple live and test sites before releasing them publicly, but every install is different. Your site may have a particular plugin installed that is incompatible, or you may have some custom code running in your theme. That’s why it is still important to test the new version with your own store.

Administration Screens to Test

These are the most important administration screens you should visit in order to check that features are working:

• WooCommerce > Subscriptions: the main subscriptions page. Here you should see all of your existing subscriptions in the new table design.
• WooCommerce > Subscriptions > Add Subscription: on the administration screen above, click the Add Subscription button to load the new Add Subscription administration screen. Create a new subscription with products, taxes and shipping. Set the subscriber’s billing and shipping address and a billing schedule to test out the new feature and ensure it works with all of your existing plugins.
• WooCommerce > Subscriptions > Edit Subscription: on the subscriptions administration screen above, click the ID of a subscription under the Subscription column to load the new Edit Subscription administration screen. Here you may be able to modify an existing subscription, depending on whether the payment gateway used to purchase the subscription supports modifications.
• Now visit other administration screens, like the WooCommerce > Orders, WooCommerce > Orders > Edit Order and WooCommerce > Settings > Subscriptions screens to ensure that everything is working correctly.

Front End Pages to Test

After you have tested the administration side of your site, you should test the customer-facing side of the site too. The most important front end customer interactions to test are:

• Purchasing subscription and non-subscription products via your store.
• Viewing and managing a subscription via the My Account page for a customer. You should pay particular attention to the new View Subscription page. Go here to test suspending and reactivating a subscription and try to change the address or payment method on a subscription or upgrade/downgrade a subscription item.

Step 3.4. Report Issues and Get Support

If you have any issues on your site after updating, please report them to us via support. Although we do extensive testing with every major new version of Subscriptions, there may still be bugs. We want to squash these as soon as possible and make sure your site is running smoothly with minimal interruption.

To help us do this, please include all of the information requested on the support ticket submission form. Including this information can save many hours and even days of back and forth emails to resolve issues.

Step 4. Update Subscriptions on Live Site

After you have successfully run the upgrade process on your staging site and tested compatibility with your store’s plugins and theme, you can now confidently update Subscriptions on your live site.

It’s important to run the upgrade process on your live site instead of transferring your database from staging to live, because customers may have purchased new products or renewal orders may have been automatically created while you were testing the update on your staging site.

Remember, the Subscriptions upgrade process is written in such a way that while the upgrade is in progress, customers, unauthenticated visitors, and other non-administrative users on your site can continue to browse and purchase products (including subscription products) from your store.

Upgrade Paths for Very Out-of-date Versions

To upgrade from really out-of-date versions of Subscriptions & WooCommerce is hard. WooCommerce often breaks backward compatibility, meaning you need to make sure you have a compatible version of Subscriptions prior to upgrading to that version of WooCommerce.

Below is an upgrade path to go from Subscriptions version 1.4.2, released on 1st October 2013 to Subscriptions 2.2.n, released in April 2017.

1. Upgrade Subscriptions from 1.4.2 to 1.4.7 (which includes full compatibility with WC 2.1)
2. Upgrade WooCommerce from 2.0.x to 2.1.12
3. Upgrade Subscriptions from 1.4.7 to 1.5.10 (which includes full compatibility with WC 2.2)
4. Upgrade WooCommerce from 2.1.12 to 2.2.11
5. Upgrade Subscriptions from 1.5.15 to 1.5.19 (which includes full compatibility with WC 2.3)
6. Upgrade WooCommerce from 2.2.11 to 2.3.13
7. Upgrade Subscriptions from 1.5.19 to 1.5.29 (which includes full compatibility with WC 2.3)
8. Upgrade WooCommerce from 2.3.13 to 2.4.13
9. Upgrade Subscriptions from 1.5.29 to 2.0.9 (which includes full compatibility with WC 2.5)
10. Upgrade WooCommerce from 2.4.13 to 2.5.5
11. Upgrade Subscriptions from 2.0.9 to 2.0.15 (which includes full compatibility with WC 2.6)
12. Upgrade WooCommerce from 2.5.5 to 2.6.14
13. Upgrade Subscriptions from 2.0.15 to 2.2.8 (which includes full compatibility with WC 3.0)
14. Upgrade WooCommerce from 2.6.14 to 3.0.5
15. Upgrade Subscriptions to the latest version
16. Upgrade WooCommerce to the latest version

Downgrading Subscriptions

Some upgrades include data migration routines which change the way data is stored in the database.  This means that when the software is updated, the database is updated as well. If a good upgrade routine is maintained, both types of upgrades should happen smoothly and there should generally be no need for downgrades.

There are times, though, when it may be desirable for a site manager to downgrade Subscriptions from the current version to a previous version.  Perhaps there is an error occurring in a newer version that was not present in the previous version.  However, downgrading is not without risk.

When Subscriptions is upgraded, there may be a database upgrade that takes place as well.  This would occur with minor releases, meaning the second number in the version changes. For example, a minor release would be from version 2.2.n to 2.3.n.  This also applies to major releases, meaning the first number in the version changes. For example, a major release would be from 2.n.n to 3.n.n. After upgrading from one minor or major version to another, a database update may have taken place as well.  The process of downgrading can cause problems because the database version is now greater than the software. Downgrading the software version does not downgrade the database version.

In order to bring attention to the possibility for issues brought by having differing database and software versions, Subscriptions will display a notice when the database version exceeds the software version.  If a downgrade occurs between minor releases, for example, from version 2.3.5 to version 2.2.19 and the database version is now greater than the software version, this notice will appear.

This does not mean that there are errors, but that this type of downgrade raises the possibility for errors.  The exact nature of the issues for each particular downgrade cannot be known without some investigation. For this reason, the notice appears as both a warning and a resource to get help if issues arise by opening a support ticket.

The post WooCommerce Subscriptions Upgrade Instructions first appeared on CODIBU.

• subscription products; and
• subscriptions.

This guide provides an explanation of the differences between a subscription product and a subscription. It also provides examples to illustrate those differences.

If you haven’t already, you should read the Subscriptions guide for Store Managers before continuing to get a more general introduction to the Subscriptions extension. The information here will also be easier to understand if you have read the subscription renewal process document and are familiar with WooCommerce orders.

Subscription Products

Subscription products are an extension of WooCommerce products. They are created by store managers via the Edit Product screen. They are displayed to customers in your store via the front-end of your website.

A subscription product has all the same data as standard WooCommerce products, including:

• price
• sale price
• tax class and status
• virtual and downloadable flags
• attributes (optional)
• inventory (optional)
• shipping weight, dimensions and class

Like any other WooCommerce product, subscription products can be added to the cart and purchased by customers via checkout. The purchase of a subscription product is recorded in an order and the terms for future payments are added to a new subscription.

Subscriptions

Whereas a subscription product is something offered to customers to purchase, a subscription is an agreement between your store and a customer for future transactions.

Like an order, a subscription can contain one or more products as line items. This is how subscription products are associated with a subscription. However, a single subscription can contain multiple subscription product line items, non-subscription product line items or even no product line items at all.

Subscriptions are created when:

• a customer completes the checkout process and the cart contains subscription products; or
• a store manager manually creates one via the Add Subscription administration screen.

Subscriptions are an extension of WooCommerce Orders. They have all the same data as an order, including:

• status
• customer
• payment method
• billing/shipping address
• downloadable product permissions
• product, fee and shipping line items
• notes
• totals

As well as subscription specific meta data like:

• billing interval and period
• next payment date
• trial end date
• end date
• related orders, including the original order used to purchase the subscription, renewal orders and switch orders

The main difference between a subscription and an order is that an order is a record of a transaction in the past, whereas a subscription is an agreement for transactions in the future. Because of this, a subscription also has a billing schedule to determine when future transactions will be processed.

Billing Schedule

Both subscription products and subscriptions have a billing schedule.

A subscription product’s schedule is made up of:

• Billing interval and period: defines the schedule on which renewal payments should recur for this product. For example, every 2nd week or per month
• Billing length: defines the number of payments that will be processed before the subscription ends. For example, a subscription with the billing interval and period of every 2 weeks and a length of 26 will last for 1 year.
• Trial period and interval: defines how much time should be provided as a free trial at the outset of the subscription. This length is added to any billing length. For example, a subscription with the billing interval and period of every week, a length of 52 and a free trial of 2 months will last for 1 year and 2 months.
• Synchronisation date (optional): a day of the week, month or year on which the first and future renewal payments should be processed. This date is only set when renewal synchronisation is setup.

A subscription’s billing schedule is made up of:

• Billing interval and period: defines the schedule on which renewal payments should recur for the subscription. For example, every 2nd week.
• Trial end date: a date in the past or future on which the subscription trial period will end or has ended. For subscription products purchased via the store, this is calculated based on the product’s trial period and interval.
• Next payment date: the date on which the next renewal payment will be processed, calculated using the subscriptions billing interval and period added to the last payment date.
• End date: a date in the future on which the subscription will expire or be cancelled, or a date in the past on which the subscription expired or was cancelled. For subscription products purchased via the store, this is initially calculated based on the product’s length.

A subscription product’s schedule is used to display the product’s billing terms to the customer on the product, cart and checkout pages in your store. It is also used to determine how subscription products should be grouped in the cart. However, a subscription’s billing schedule is what is used to determine the actual renewal schedule of a subscription. This schedule will override the billing schedule set on any products added to that subscription as line items.

Examples

To demonstrate the difference between a subscription product and subscription, consider the following examples.

Purchasing a Monthly Coffee Subscription Product

A typical flow of a customer subscribing to a product in your store is:

1. Customer visits your online store which sells coffee
2. Customer views a coffee bean subscription product offered by your store that ships a bag of beans every month
3. Customer adds the coffee bean subscription product to their cart
4. Customer proceeds to checkout
5. Customer completes checkout to purchase the coffee bean subscription product
6. WooCommerce creates an order to record the transaction. The coffee bean subscription product will be included as a line item on that order.
7. WooCommerce Subscriptions creates a subscription to record the agreement for future transactions. The coffee bean subscription product will also be included as a line item on that subscription.
8. One month later, the subscription will renew according to its billing schedule
9. WooCommerce Subscriptions creates a renewal order to record the renewal payment transaction. The coffee bean subscription product will be listed as a line item on that renewal order.

Manually Create a Subscription for a Monthly Service Fee

Imagine a store that wants to manage payments for a regular service of $100 / month. The store does not publicly sell this service, so it does not need to create a subscription product to offer it to the public in the store.

Instead, it is possible to manually create a subscription that is not associated with any products and charges a $100 fee each month.

To do this, the store manager can:

1. Go to WooCommerce > Subscriptions > Add Subscription screen
2. Add a subscriber/customer to the subscription
3. Set the billing schedule to renewal each month
4. Add a fee to the subscription for $100 (but do not add product line items)
5. Calculate recurring totals
6. Set subscription status to active
7. Save the subscription

This will create a subscription that renews each month and creates a renewal order for $100 as a fee line item. It is not associated with any subscription products.

Note: This example is provided to illustrate the difference between products and subscriptions. Creating subscriptions with only fee line items is not recommended. Doing so leads to a number of issues, including:

• it won’t be possible to get sales statistics for that line item using the WooCommerce Reports, as the reports only work for products.
• the customer will not be able to manually pay for orders associated with the subscription, including renewal orders, because Subscriptions uses the WooCommerce cart to pay for these orders, and WooCommerce requires products to be added to the cart for checkout to be possible.

Adding a Monthly Subscription Product to an Annual Subscription

To illustrate how a subscription’s billing schedule can override the billing schedule set on individual products added to that subscription as line items, consider the following two items:

• a subscription for $100 / year;
• a subscription product for $25 / month.

If the $25 / month subscription product is manually added as a line item to the subscription, it will not change it’s billing schedule. The subscription will continue to renewal annually, unless the the billing schedule is also manually changed.

Changing Product Line Items Over a Subscription’s Lifecycle

Using additional plugins, like AutomateWoo or All Products for WooCommerce Subscriptions, it’s also possible for a subscription’s product line items to change over its lifecycle.

For example, with AutomateWoo’s Add/Remove Product actions it’s possible to setup monthly magazine subscriptions and have a different product and SKU for each month’s magazine included on each month’s renewal order. This is done by creating a workflow which:

1. Runs after a renewal payment; and
2. Removes the previous month’s magazine as a product line item
3. Adds the next month’s magazine as a product line item so that

While the products on the subscription change, no other subscription details, like its billing schedule or shipping address, will be changed.

Each month’s magazine also does not need to be a subscription product, it can be a simple product available for one-off purchases in your store.

Similarly, with All Products for WooCommerce Subscriptions, it’s possible to add a non-subscription product to an existing subscription. For example, a customer could add a different kind of coffee bean to their existing monthly subscription to another type of coffee bean.

Again, while the products on the subscription change, no other subscription details, like its billing schedule, will be changed when the new product is added.

Subscription Products vs Subscriptions Summary

A subscription product is something offered to the customer for purchase in your store. For most stores, store managers will only ever need to create subscription products. When customers purchase those products, subscriptions will be created automatically. These subscriptions keep a record of the agreement for future transactions of those products. They will also manage the renewal process to process payments and create orders to record those transactions.

The post Subscription Product vs Subscription first appeared on CODIBU.

This guide provides an overview of the decisions made to implement multiple subscription handling. It is intended to provide a non-technical overview. For a technical document on how mulitple subscriptions are implemented, refer to the Developer Guide to Multiple Subscriptions.

Before continuing with this guide, it will be helpful to understand the difference between a subscription product and a subscription and the subscription renewal process.

Goals for Multiple Subscriptions

The reasons store managers requested it be possible for customers to purchase different subscription products were:

• to prevent making customers repeat the entire checkout process for each subscription product they wished to purchase;
• to reduce payment gateway fees by processing the sign-up and renewal of multiple products in the one transaction (most payment gateways charge a flat per transaction fee); and
• to consolidate renewals and reduce the number of renewal orders created to avoid having to process multiple orders for the one shipment to a customer.

Challenges of Multiple Subscriptions

Designing a system for purchasing products with thousands of possible combinations of billing schedule creates a number of challenges.

The key challenges in designing a system to handle multiple subscriptions were:

• account for shipping calculations, which can be charged per order, per item, per shipping class and any combination of the above.
• present all relevant information about the billing agreements being made between the customer and the store, including recurring taxes and shipping amounts, while avoiding presenting so much information on the checkout page that the customer feels overwhelmed or confused and abandons the checkout.
• create a system that is straight forward for store managers to understand and does not create excessive overhead for managing subscriptions and renewal orders.

Solution: Grouping Subscriptions

After examining a number of alternatives, the method chosen to make it possible to purchase different subscription products was to group each subscription product with an equivalent billing schedule into the one subscription.

For example, if a customer purchases 2 x monthly subscriptions and 3 x yearly subscriptions in the one transaction, only 2 x subscriptions would be created – one with two line items for the monthly subscription products and one with three line items for the annual subscription products.

This allows recurring shipping costs to be accurately calculated and displayed during sign-up, while also consolidating renewal orders and reducing payment gateway fees for subscription products purchased in the same transaction.

Details of Grouping

WooCommerce Subscriptions will create the minimum number of subscriptions possible. To do this, it will group subscriptions based on each product’s:

• billing interval and period, to make sure the billing schedule for all products is honoured.
• subscription length, to make sure the end date can be set correct for each subscription product.
• first renewal date, to account for products with a free trial or synchronised renewal date.

For example, all of the following subscription products would be grouped together:

• $10 every 2nd month
• $25 every 2nd month with 2 months free trial (because the first renewal date after the free trial is equivalent to the first renewal date of the product without a free trial)
• $30 every 2nd month synchronised to today’s date

On the other hand, none of the following subscription products would be grouped together:

• $10 per month
• $10 per month for 12 months
• $10 per month synchronised to tomorrow’s date
• $10 per month with 2 weeks free trial

Cart Grouping

The lifecycle for a subscription product is: Product > Cart > Checkout > Order > Subscription.

To support the purchase of multiple subscription products in the one transaction, the cart therefore needs to be able to contain multiple subscription products.

As the products will be grouped into subscriptions after checkout, the products are also grouped in the cart based on billing schedule. This also allows for the recurring totals to be displayed based on the grouped billing schedules, reducing the number of rows that need to be displayed to the customer to accurately present the recurring tax, shipping and total.

Grouped Recurring Total Display

Subscriptions v1.5 displayed the recurring totals alongside the order totals on the cart and order review pages. However, by supporting multiple subscriptions in the one transaction, different billing schedules need to be displayed to the customer to fully communicate the commitment of the subscription.

A new Recurring Totals section was added below the existing order totals section to display this information. Each groups of subscription products will have a row in the Recurring Totals section for:

• subtotal
• shipping
• taxes
• discounts
• total

Order Grouping

As mentioned above, after purchasing multiple subscription products in the same transaction, the products with the same billing schedule will be grouped together as line items on the one subscription object (as opposed to each subscription having only one product/line item associated with it).

For example, the three screenshots below show:

• an order used to purchase 4 subscription products – it has 4 line items; and
• two subscriptions created to store data for the 4 subscription products – each has 2 line items.

Issues with Grouping

No design is perfect, and as such, this implementation did introduce some new issues. These issues and the solutions are:

• a customer could no longer cancel subscriptions to an individual item. This was resolved by adding a remove item button on the View Subscription page to allow the customer to remove individual items.
• switching was previously done per subscription, which would not work with a subscription that has multiple line items. As a result, this process has been updated to be per item, instead of per subscription.
• subscription products purchased separately are not grouped together, which results in extra renewal orders and gateway fees. This issue has not been addressed with v2.0 and instead, may be address in a later version or as a separate extension in the form of a Add to Subscription button. This can replace or be displayed alongside the Add to Cart button, allowing customers to add new products to an existing subscription, rather than creating a new subscription, while still requiring them to review and agree to the shipping costs of that subscription.

Alternative Implementation

Before deciding on Grouping Subscription products, alternative implements were explored, including an implementation which created a separate subscription for each subscription product purchased in the transaction.

For example, if a customer was to purchase 2 x monthly subscriptions and 3 x yearly subscriptions in the one transaction, 5 x subscriptions would be created with each including a single line item for that product.

Issues with this Design

This system would be most similar to the existing design, but it did not take full advantage of the flexibility of the changes being introduced in v2.0. It applied the constraints of the previous designs to the new architecture.

Furthermore, to achieve the goal of consolidating renewal orders and reducing payment gateway fees, this system would need a batch processing system to group each subscription’s renewals into the one order.

Batch processing created a major issue: shipping could not accurately be calculated and agreed to on checkout at the time of sign-up. Because some shipping methods charge per order, and subscriptions were batched into renewal orders, any time a customer purchased new subscriptions or cancelled existing subscriptions, the shipping amount would be different at renewal to the time of sign-up. This issue was found unavoidable and would ultimately introduce an unfixable bug. As a result, create a single subscription and batch processing all renewals was not chosen as the final implementation.

Alternative Recurring Totals Display

A few options were explored for how to display recurring totals for multiple subscriptions, including:

1. do not display the totals;
2. continue to display recurring totals inside of the order totals section;
3. add a new Recurring Totals section below the existing order totals section to display recurring subtotal, shipping, taxes and total.
4. display a complete order table for each subscription below the Sign Up Now/Place Order button.

The first of these is not legal in many countries so was not seriously considered. The second would make the order totals section very crowded, while the fourth included a lot of duplicated information.

As a result, the Recurring Totals section was chosen as it was the most concise method that still provided accurate information for each recurring amount.

The post Store Manager Guide to Multiple Subscriptions first appeared on CODIBU.