This guide will explain why this notice is displayed, likely causes of the issue, steps to diagnose the cause, and how to fix the problem or get help.

Scheduled Action Timeout Notice

As mentioned in Action Scheduler housekeeping, if an action has been “running” for more than five minutes, it is considered to have timed out and is marked as failed. This is because if an action has been running for that length of time, it is likely not actually running at all. When a subscription-related action fails due to a timeout, a notice is displayed in the admin dashboard.

Fixing Affected Subscriptions

Step 1 – Finding the Affected Subscription

The notice that appears after an action timeout contains a note with the subscription number and a link to the edit subscription page for that subscription. This can be used to investigate if there are issues with the last renewal payment for that subscription that need to be manually addressed.

Step 2 – Tracking When the Payment Process Was Affected

The first step to this is to see if payment was actually affected. This can be done by tracking when the payment process was affected.

Tracking the Renewal Process

For a renewal order, each stage of the renewal process is documented on the subscription in its notes. To view this process:

1. Go to the WooCommerce > Subscriptions > Edit Subscription screen
2. View the Subscription notes 

    

   
   

3. The normal process for a renewal follows:
   1. When a renewal is due, the subscription is moved to an On-hold status
   2. An order is created to record the renewal
   3. If the subscription is on automatic renewals, the order attempts to process payment and may mark complete
   4. Once payment is complete, the subscription is moved to Active status 

       

      
      

4. Each step above records the date and time at which it was processed.

Comparisons can be made between the payment process and the failed action in order to find out when the process timed out.

Failure Before Payment

If the renewal order was created but the payment was not marked complete, the process may have stalled before payment was processed. This can be indicated if the time of failure of the action, as found above, is close to the time of the creation of the renewal order.

To make sure that the payment was not captured, there are a couple steps to take.

1. Go to the created order, linked to in the Subscription notes
2. Check the Order notes on the order to see if the status changed and the payment was processed

    

   
   

3. Log in to the chosen payment gateway’s store account and check if the charge was captured for that order.

If there is no charge, then the processed stalled before payment was taken.

Failure After Payment

If payment was captured but the order was not marked Processing or Complete or the subscription was not transitioned to an Active status, then the process stalled after payment. This can be indicated if the time of failure of the action, as found above, occurs after the payment was marked complete.

Step 3 – Fixing Affected Subscriptions and Orders

Affected Before Payment

If payment was not captured:

1. On the existing renewal order, change the status to Cancelled and Update.
2. Set the subscription status to Active and Update.
3. Choose Process renewal from the subscription option dropdown.
4. This will then create a new renewal order, which should process as normal.

Affected After Payment

If payment was captured but the order and subscription were not updated:

1. If the renewal order was not marked Processing or Complete, change the status to the appropriate status. This will also update the subscription to Active.
2. If only the subscription was not transitioned, set the subscription status to Active.

Diagnosing the Cause

It’s impossible to programmatically identify the cause of a timeout. Instead, they always require manual investigated, which is why this notice is displayed. There are a number of possible causes, as outlined below, which should be explored to find the cause of the timeout.

Subscriptions Version

These timeouts, and thus the error notices, are expected to be extremely rare occurrences with Subscriptions 2.4.3 or newer.

If this notice appears on a site running a version of Subscriptions less than 2.4.3, the first step is to update the Subscriptions version.

If a site is currently running a Subscriptions version greater than or equal to 2.4.3, the version of Subscriptions at the time of the error should be checked. Even if Subscriptions has since been updated, it is important to note what version was running at the time the notice first appeared.

In order to check the version of Subscriptions running when the error occurred:

1. Review the WCS Upgrade log and the Failed Scheduled Actions log
2. Compare the time the error is logged in the Failed Scheduled Actions log to the version running at that time, as found in the WCS Upgrade log

If a Subscriptions version less than 2.4.3 was running at the time of the error and Subscriptions has since been updated, the underlying issue has likely been resolved.

If the version of Subscriptions was newer than that at the time of the error, further investigation is needed.

PHP Time Limit

The PHP time limit is the amount of time the server will spend on a single process before timing out. A time limit that is too short can cause processes to time out. A common default value is 30 seconds, and many managed hosts provide a longer timeout period.

To find the PHP time limit for your server:

1. Go to WooCommerce > Status to view the system status
2. Scroll down to the Server environment section
3. View the PHP time limit 

    

   
   

If this limit is below 30 seconds, we recommend increasing it to avoid scheduled action timeouts.

To change this limit, contact your hosting provider and discuss with them the best way to change the time limit if possible.

Large Number of Timeouts

This kind of notice and timeout is expected to be a very infrequent occurrence, and certainly not something that occurs repeatedly. In sites where there are dozens of timeouts or more, there is likely a critical underlying problem causing the timeouts that will need to be addressed.

To check the number of timeouts review the Failed Scheduled Actions log.

If there are many timeouts, please open a support ticket.

Further Help

If you would like further assistance, please open a support ticket.

In the support ticket, please include the system status, so we can find your site’s PHP time limit and plugin versions, and the name of your host, so we can investigate their specific server limitations. If in Step 1 you were able to determine the active version of Subscriptions at the time of the error, include this as well. Please also include an admin login so that we can access your site.

The post Subscriptions Scheduled Action Errors first appeared on CODIBU.

A number of issues can arise from disabling WooCommerce Subscriptions, such as for:

• Any dependent plugins
• Renewal payments
• Expiration upon the subscription’s end date
• Cancellation after the end of the prepaid term is reached
• Automatic retry of failed payments

Additionally, simply disabling the plugin may not completely stop all the actions associated with it, such as renewal payments.

Disabling Subscriptions Actions

If choosing to disable Subscriptions, steps will need to be taken to completely stop all associated actions. Scheduled actions, such as renewal payments, are processed in Subscriptions by a job queue library called Action Scheduler.

If another plugin, such as WooCommerce Memberships, Follow-up Emails, or WooCommerce version 3.5 or greater, is active on the site, then they will also be loading a version of Action Scheduler to process their own scheduled actions. In this case, the scheduled events for Subscriptions will continue to be processed, even if Subscriptions is inactive.

To check if another plugin is loading Action Scheduler:

1. Disable Subscriptions
2. Visit the admin screen at https://example.com/wp-admin/tools.php?page=action-scheduler, replacing example.com with your site’s URL

    

   
   

3. If the page loads, another plugin is using Action Scheduler

If nothing else is loading Action Scheduler, the queue will remain but be inactive. This means that it will still be there and continue to run if Action Scheduler is activated, either by re-activating Subscriptions or another plugin that uses Action Scheduler.

If Action Scheduler is still active and you do not want to disable the other plugins, it is possible to stop Action Scheduler from running. In order to completely stop Action Scheduler from running, download, install, and activate the Action Scheduler Disable Default Runner plugin. This plugin will stop the Action Scheduler queue from running altogether.

This means that all actions for all plugins using Action Scheduler will stop. If you need to continue processing actions for other plugins, please open a support ticket.

Disabling a Payment Gateway Plugin

It is also possible to disable a specific payment gateway plugin. If a gateway plugin is disabled while Subscriptions is active, those subscriptions that use that gateway will be converted to use manual renewals. This means that the subscriptions can be paid for, but the customer will need to log in and pay for the subscription using a different gateway, rather than a payment being automatically processed.

The post Disabling Subscriptions first appeared on CODIBU.

Logs can be found on the dashboard of a site. To view the logs:

1. Go to WooCommerce > Status
2. Click on the Logs tab
3. Choose a log from the drop-down

Log names will begin with the given labels, but will sometimes then have a date and a string of letters and numbers, called a hash, added to them. This is to ensure that each log has a unique name and is not overwritten.

Error Logs

Failed Status Change Logs

This log is labeled wcs-update-status-failures. This log records when there has been an error when updating the status of a subscription.

Example log entry:

Failed Scheduled Action Logs

This log is labeled failed-scheduled-actions. This log records when a scheduled action has failed. It will contain information such as the scheduled action’s name and ID, how long it was attempted, and the arguments.

Example log entry:

Failed PayPal IPN Logs

This log is labeled wcs-ipn-failures. This log records fatal errors that occur while a PayPal IPN is being processed. These error messages will contain info such as a stack trace for where the error occurred.

Example log entry:

PayPal Logs

This log is labeled paypal. Subscriptions does not generate this log, but adds to it. This log records PayPal IPNs, the actions taken with them, and errors.

Example log entry:

Caching Event Logs

This log is labeled wcs-cache. This log records events related to caching, such as clearing the cache of a particular subscription. WCS_DEBUG must be on for this log to populate. The methods that use this cache were deprecated in Subscriptions version 2.3.

Example log entry:

Upgrade Logs

When WooCommerce Subscriptions is upgraded to a new version, for example, from version 2.4.7 to 2.5.0, it records some information about the upgrade process in a variety of logs.

General Upgrade Notes Logs

This log records during upgrades and contains:

• Timestamp of when the upgrade occurred
• Version of Subscriptions being updated to
• Old version of Subscriptions updated from
• WooCommerce version during this upgrade
• WooCommerce database version
• Environment info, which includes WordPress version
• Info about active plugins, such as name, author, and version

The information in this log is automatically deleted after eight weeks. This log is labeled wcs-upgrade.

Example log entry:

Update Post Author Column Logs

This log is labeled wcs-upgrade-subscription-post-author. WooCommerce 3.5 began storing the customer ID associated with an order in the post_author field of the wp_posts table. Previously, this information was stored in post meta as _customer_user, and will continue to be stored there as well for backwards compatibility. This change should result in performance improvements when filtering by customer ID. Subscriptions 2.4 includes an upgrade to follow this change and store the customer ID associated with a subscription in the post_author field as well, but only for stores running WooCommerce 3.5 or greater. This log records the subscriptions that had the customer ID added to the post_author column or errors that occur in that process.

Example log entry:

Migrate Payment Retries to Custom Tables Logs

This log is labeled wcs-retry-migrator. Subscriptions 2.4 migrates payment retry data to custom tables. This allows potential performance improvements for sites with payment retry data. This log records the payment retry id, the table it was migrated to, and its new id.

Example log entry:

Add Start Date Meta Data Logs

This log is labeled wcs-add-start-date-metadata. In Subscriptions 2.4, a metadata change was made to have separate entries for a subscription’s created date and start date. This is not a visible change at the moment, but the data on existing subscription will be updated. In the upgrade process for Subscriptions 2.4, a script will run that will add the start date meta data. This log records the subscriptions that have meta data added or errors that occur in that process.

Example log entry:

Add Subscription Address Index Logs

This log is labeled wcs-add-subscription-address-indexes. In the upgrade process for Subscriptions 2.3, a repair script will run to add address indexes for subscriptions created before WooCommerce 3.0 was in use, which is when address indexes were added. This log records the subscriptions whose addresses are updated or errors that occur during that process.

Example log entry:

Repair PayPal Suspended Subscriptions Logs

This log is labeled wcs-upgrade-subscriptions-paypal-suspended. In the Subscriptions 2.3 upgrade, a repair script aligns subscriptions that were suspended in PayPal but not in WooCommerce. Due to a bug that was present from Subscriptions version 2.1.4 to 2.2.8, there were rare circumstances in which subscriptions in WooCommerce became out of sync with PayPal. This log records the subscriptions that were repaired or errors that occurred during that process.

Repair Contains Synced Variation Subscriptions Logs

This log is labeled wcs-upgrade-subscriptions-containing-synced-variations. In Subscriptions 2.2.0, there was a bug that meta data _contains_synced_subscription was not set in the case that a subscription containing a synced product variation was purchased when running WooCommerce version 3.0 or greater. This bug was fixed in Subscriptions 2.2.8. The upgrade to Subscriptions 2.2.9 contains a script that repairs the existing subscriptions that were created between versions 2.2.0 and 2.2.8 by adding that meta data. This log records the subscriptions that were repaired, those that needed no repair, and errors that occurred during that process.

Example log entry:

Repair End of Pre-Paid Term Subscriptions Logs

This log is labeled wcs-upgrade-end-of-prepaid-term-repair. In Subscriptions 2.2.0, there was a condition which caused cancelled subscriptions to not schedule the action that would transition these subscriptions to cancelled status. The upgrade to Subscriptions 2.2.7 contains a script that repairs this and schedules the end of prepaid term actions. This log records the subscriptions that were repaired by immediate cancellation or adding an end of prepaid term action, those that needed no repair, and errors that occurred during that process.

Example log entry:

The post Subscriptions Logs first appeared on CODIBU.

This guide will outline how to fill out the support ticket form for getting help with this WooCommerce extension so that the support team can provide the most meaningful and quickest service. It will step through using an example ticket for WooCommerce Subscriptions as if a PayPal IPN error occurred on a site. This general advice can be transferred to other errors and tickets.

Components of a WooCommerce Subscriptions Ticket

The support form has a number of fields, each with the purpose to obtain information that will provide the best context to the support team. This context will help them investigate and solve the problem. Below is a fully filled-out ticket and a breakdown of each section.

Extension Field – Choose Subscriptions

The first field is a drop-down from which to select the extension that seems to be causing the issue.

In some cases, it may be difficult to pinpoint which extension is causing the problem. The symptoms of the issue should be a good start. For example, if a subscription did not renew when it was supposed to, it might have to do with WooCommerce Subscriptions.

Sometimes, there may seem to be an issue with one plugin when it is actually the problem or conflict of another. Don’t worry if it is difficult to pinpoint the cause, the support team will investigate and do their best to help solve the issue even if that means forwarding the ticket to the right extension developer.

A few questions to ask yourself about the originating plugin:

1. What plugin is the affected functionality from?
2. If there is an error, what plugin was mentioned in the error, if any?
3. Does deactivating the plugin resolve the issue?

Ticket Subject Line

The subject line is a great place to provide a concise summary or main issue or purpose of the ticket.

A few questions to ask yourself about filling in this line:

1. What is the most salient problem?
2. How can the issue be summed up?
3. What is the main symptom?

Ticket Body

In this section, describe the full extent of the issue. The following information can all be helpful:

• background of the issue
• steps to reproduce
• copy/paste of any error message
• the ID numbers of specifically affected products, orders, or subscriptions, and
• screenshots of the issue. A service like CloudUp will make this easy to share.

While this section does not need to be long, a few key details can provide a lot of context for investigation.

This is also the place to provide details about login information for an admin account.

A few questions to ask yourself when filling in this section:

• What sequence of events happened to bring about this issue?
• What is the end result and which specific parts of the site are affected?
• Are there any error notices appearing?
• Did I create and include an admin login?
• If I was reading this message and had no background or context for it, would I understand the issue and be able to investigate it?

Your Store’s URL

In this section, list the URL of the affected site. This is a straightforward field, but make sure to include it so support knows where to look.

Store’s Status Report

When dealing with WooCommerce and Subscriptions, this section is quite important to include. The system status report includes information about the site, including WooCommerce version, a list of plugins and their versions, whether the site is in staging mode, and many other useful pieces of information. This type of information helps the support team to better understand the context of the issue.

In order to include the system status report:

1. In the WordPress Dashboard, go to WooCommerce > Status
2. In the info box at the top of the page, press the Get system report button
3. Then press Get for support button
4. Paste into the Website Status Report field on the support ticket form

Temporary Admin Access

Creating and including an admin account is an important step to take for tickets that are not simply questions.

WordPress installs are not connected in a centralized system. This means that unless we have access to your site, there is no way for support to view the back end (dashboard, etc.) of the site. An administrator account allows us access to what the store manager sees as well as error logs and much more information that will be important for investigation.

This can be a temporary user account, which can be deleted once the issue is resolved.

Please reference the detailed guide on the best way to create an admin user for us.

After Submitting a Ticket

If you don’t see a response from us, please make sure to check spam or junk folders in case the response was filtered.

The post Opening a Subscriptions Support Ticket first appeared on CODIBU.

Do these changes apply to me? 

The new requirements from Visa apply to your business if you offer subscription products with a free trial and collect credit card information at the time of signup.

These new requirements do not apply to transactions involving:

• Subscription products without a free trial.
• Where the first payment on a subscription product is discounted by the use of a coupon instead of a free trial.
• No credit card information at the time of sign-up.

What changes do I, as a merchant, need to make?

The changes are designed to make sure customers are given clear details of the subscription’s billing terms, can more clearly identify free trial transactions and to ensure they can take action on the subscription.

Many of the requirements are already met by WooCommerce Subscriptions. However, there are a couple of changes you will need to make if you offer subscriptions with free trials and collect billing information from the customer at the start of the trial.

Sign up for free trial without payment details

In WooCommerce Subscriptions 2.5, a new feature was introduced that allows customers who sign up to free trial subscriptions to do so without a credit card. If your store has this enabled, you will meet the requirements of this rule change since no payment details are taken during sign up. 

To enable this feature:

1. Go to the WooCommerce > Settings > Subscriptions screen.
2. Scroll down to the Miscellaneous section.
3. Check the option to Allow $0 initial checkout without a payment method.
4. Save.

Learn more about this feature in our WooCommerce Subscriptions 2.5 guide.

Express Consent

At the time of enrollment, merchants must require the cardholder to expressly consent to entering an ongoing subscription service for recurring payment. 

Visa

To meet this requirement you will need to collect expressed consent from the customer before taking payment, consent that they are entering an on-going subscription service with a recurring payment component. In obtaining this consent you will need to provide the following details to the customer:

• Details of the goods and services provided.
• The start and end date of the subscription.
• The length and price of the free or promotional trial period.
• The cost of the subscription after the trial period ends.
• The number of reminders that will be sent prior to billing (note that a trial-ending reminder email is required at least 7 days before the end of a trial period).
• The cancellation policy, including the steps a customer must follow to cancel a subscription. 
• The date on which the customer can expect to be billed, for example, if it will be the same date of each month.

Already Included in WooCommerce Subscriptions Checkout

During the normal checkout process with WooCommerce Subscriptions, the following are included in the order review section on your store’s checkout page:

• Details of the goods
• The start and end dates of the subscription
• The length and price of the free trial period
• The cost of the subscription after the trial period
• The date on which the customer can expect to be billed

What You Will Need to Add

If you are offering subscriptions with a free trial, the two requirements that are not already handled by Subscriptions are:

• The cancellation policy, including the steps a customer must follow to cancel a subscription.
• Reminders sent prior to billing (note that a trial-ending reminder email is required at least 7 days before the end of a trial period).

Cancellation Policy

To meet this requirement you will need to include the following in the checkout process so that customers can provide consent:

• Your cancellation policy
• Details about the number of reminders that the customer can expect prior to the recurring billing component starting
• The steps a customer must take to cancel a subscription in your terms and conditions

This can be done by editing your Terms & Conditions page, which is included in WooCommerce.

Any subscription that begins with a free trial period must have a mechanism to cancel it before the recurring billing period begins. By default, WooCommerce Subscriptions allows customers to cancel their subscriptions at any time from their My Account page. If you have removed this option, it will need to be reinstated to comply with this condition.

Reminders Prior to Billing

To meet this requirement, you must send a notification to customers 7 days prior to the trial end and the payment taking place.

There are a variety of solutions to notify subscribers before a renewal takes place. One way is to use AutomateWoo, which integrates with WooCommerce Subscriptions. Check out more about using AutomateWoo with Subscriptions for info on the integration.

Enhanced Statement Descriptors

Note: Due to COVID-19, Visa have delayed this requirement until April 17, 2021. 

Visa

To assist customers with identifying free trial transactions, the first transaction description, after the free trial period, will need to include ‘trial end’ or ‘trial over’. 

This is the description which appears on the customer’s bank statement, and in mobile banking apps.

This will be handled by your payment gateway extensions. Please be sure to look out for updates to your payment gateway extensions, to comply with this new requirement. 

If you are unsure whether your payment gateway plugins meet this requirement, please reach out to them through their support channels. 

Additional Requirements for Stores Operating in the EU 

If you sell to customers located in the EU, you will also need to:

• Provide the customer with confirmation of the establishment of the recurring payment agreement, within 2 days of purchase. To meet this requirement, the WooCommerce order processing email sent immediately after the order is paid has been updated to include a note about automatic recurring payments.
• At least 7 days before each recurring transaction, send an email or SMS notification to the customer to remind them about the key features of the recurring payment agreement if:
  • A trial period is ending.
  • More than 6 months have elapsed since the previous recurring payment.
  • The recurring payment agreement has been changed, including the amount of the recurring payment, the date of the recurring payment, or any other terms of the agreement. To meet this requirement, we recommend AutomateWoo as it can process bulk subscription billing updates and has support for notifying customers of those changes. See AutomateWoo’s guide to learn more.

To meet the requirements of more advanced pre-renewal notifications we recommend using one of the plugins and services listed in our pre-renewal email guide.

The post 2020 New Visa Requirements for Subscriptions with a Free Trial first appeared on CODIBU.

The post Subscriptions Guided Tour first appeared on CODIBU.

To prevent duplicate payments from a clone of your site, Subscriptions will disable automatic payments and subscription-related emails whenever the current site’s URL differs to the URL of the site where Subscriptions was first activated.

Duplicate Site Warning

You will know when the site is in staging mode because Subscriptions will display a warning in the administration area of your site. This notice also shows which URL Subscriptions considers to be the live site.

Subscriptions will also display a smaller warning next to the WooCommerce > Subscriptions menu item when a store is operating in Staging Mode.

You can still test subscription renewals on a test site, but Subscriptions will use the manual renewal process and will not send any subscription-related emails.

It is possible to enable automatic payments and to send subscription-relation emails on a staging site.

Please note: it is only emails sent by Subscriptions that will be blocked by Subscriptions in staging mode, any emails sent or managed by WordPress, WooCommerce or another plugin may still be sent from your staging site. To block all emails from your site, install a plugin like Disable Emails.

What does Subscriptions consider a Staging Site?

Subscriptions will keep a record of the URL of the site where it is first activated. It considers this to be the live site and will run in live mode. If the site’s URL then changes, it considers the new site to be a staging site and it will run in staging mode.

This means if you first activate Subscriptions on a staging site, Subscriptions will run in live mode on the staging site because it considers this site to actually be your live site.

Because of this, if you want to test Subscriptions on a staging site before running it on your life site, we recommend first activating it on the live site and then creating the staging site from that site’s database.

Developer Note: Subscriptions stores a clone of WordPress’ siteurl value in an option with the name wc_subscriptions_siteurl. It compares this value with the siteurl value to see if it has changed.

Check if Staging Mode is Active

If you are unsure whether you or another administrator on the site has dismissed the notice and want to check if the store is running in Staging mode, you can:

1. Go To WooCommerce
2. Check the Subscriptions menu item. If a red area is shown with the word Staging, the site is in Staging Mode. If nothing is displayed except “Subscriptions”, the site is in Live Mode.

Whether the store is running in Staging or Live mode is also displayed on the Status screen. To check it there, you can:

1. Go To WooCommerce > Status
2. Scroll down to Subscriptions Mode
3. Check the value. If a red cross is shown with the word Staging, the site is in Staging Mode. If a tick mark is shown with the word Live, the site is in Live Mode.

Below this section will be a row labeled Subscriptions Live URL. This shows the URL that Subscriptions considers to be the live site.

Enabling Automatic Payments on a Staging Site

To switch your site from Staging Mode to Live Mode:

1. Go to any administrator page on your site, e.g. visit example.com/wp-admin/
2. Click the Enable Automatic Payments button displayed in the staging site notice.

If you chose the Quit Nagging Me option, but then later find you want to enable automatic payments on the staging site, you can:

1. Go to example.com/wp-admin/?wcs_display_staging_notice=true while logged in as an administrator, replacing example.com with your site’s URL

Alternatively, you can:

1. Access your database via PhpMyAdmin if your host provides it (or install a plugin like WP phpMyAdmin if your host does not provide phpMyAdmin access)
2. Search the wp_options table for an option with the option_name of 'wcs_ignore_duplicate_siteurl_notice'
3. Change the option value of the 'wcs_ignore_duplicate_siteurl_notice' option to anything other than its current value, “false” would be a good choice.
4. Save the changes to the option value

The staging site notice should reappear and you can choose to Enable automatic payments.

Database Migration

When migrating your site’s database from one server to another server, there are additional considerations.

If you have migrated your site’s database and the domain name has not changed, the staging mode will not be triggered on the new site. This means renewal payments will be processed in live mode. If you want to make sure payments are not processed, even temporarily, you need to:

• Change the site URL for it, this will switch that site into staging mode; or
• Disable Action Scheduler’s default queue runner to ensure Subscriptions doesn’t trigger renewal events.

Decommission the old site

To avoid any issues with duplicate payments or emails, you should decommission the old site as soon as possible.

However, if you need to continue to allow the old site to run after migrating the database to a different server, you must also:

• Change the site URL for it, this will switch that site into staging mode. In some cases, wc_subscriptions_siteurl value might need to be updated as well, the option can be found under https://YOUR-DOMAIN.com/wp-admin/options.php (replace YOUR-DOMAIN.com with your own domain URL); or
• Disable Action Scheduler’s default queue runner to ensure Subscriptions doesn’t trigger renewal events.

Without completing one of these steps, your old site will continue to process real recurring payments.

We also suggest you block all emails from your duplicate site to prevent customers receiving any emails from this old site. To do this, you can use a plugin like Disable Emails (this plugin is not officially endorsed by WooCommerce.com).

Disabling All Scheduled Events

By default, scheduled renewals and other scheduled events, like expiration, will still be triggered when Subscriptions is in staging mode. No payments will be attempted, or emails sent, for these events, but the event will still be initiated as it would be on the live site.

If you wish to stop these events being triggered, install and activate the free Action Scheduler – Disable Default Runner plugin.

This plugin disables all events in the scheduling library WooCommerce Subscriptions uses. This library is also used by other extensions, like WooCommerce Memberships, so will also disable any scheduled events for those plugins.

Enabling Subscriptions Emails on a Staging Site

If you would like to enable subscription-related emails on a staging site, you can define the WCS_FORCE_EMAIL constant.

In order to enable this constant:

1. Go to your site’s wp-config.php file
2. Above the line that says /* That's all, stop editing! Happy blogging. */, add:

    

   if ( ! defined( ‘WCS_FORCE_EMAIL’ ) {
         define( ‘WCS_FORCE_EMAIL’, true );
   }

3. Save file

FAQ

Why are renewal payments not processing on the live site?

When a renewal is processed in Staging mode, the following note will be added to its order notes:

Payment processing skipped – renewal order created on staging site under staging site lock. Live site is at https://example.com/

On occasion, these notes may appear on renewal orders created on the live site. This means the live site is accessible via more than one URL. For example, the site may be accessible via both:

• https://www.example.com
• https://example.com

To process renewals correctly, Subscriptions requires your WordPress site to be accessible via only one URL.

To ensure your site is accessible via only one the URL, you can use the WordPress Site URL constants in your wp-config.php file to set the URL for the site. For example:

define( 'WP_SITEURL', 'https://example.com' );
define( 'WP_HOME', 'https://example.com' );

You should also make sure your web server software, like Apache, is configured to redirect any requests to other URLs to the canonical URL. WordPress has a guide on setting up .htaccess file correctly. If you need additional help, please contact your web host.

Serving your site under a single URL is good practice as it has other benefits, most notably for SEO. As Moz explains:

Duplicate content is content that appears on the Internet in more than one place. That “one place” is defined as a location with a unique website address (URL)

While not technically a penalty, duplicate content can still sometimes impact search engine rankings. When there are multiple pieces of, as Google calls it, “appreciably similar” content in more than one location on the Internet, it can be difficult for search engines to decide which version is more relevant to a given search query.

Why are emails still being sent on my staging site?

WooCommerce Subscriptions will only block emails sent by it when in staging mode. Emails sent or managed by WordPress, WooCommerce or another plugin may still be sent from your staging site.

To block all emails from your site, install a plugin like Disable Emails.

The post How Does Subscriptions Handle Staging Sites and Migrations? first appeared on CODIBU.

When PayPal processes a payment or other subscription event, like a cancellation, it sends an IPN to the site. Subscriptions processes this IPN and performs the appropriate actions concerning the related orders and subscriptions.

For example, when a recurring payment is due, payment occurs via PayPal and an IPN is sent confirming that the payment was processed. The site receives this message, creates an order to record the transaction and sets the status of the corresponding order and subscription to reflect the processed payment.

On occasion, errors occur when processing an IPN. The reasons for the errors vary. A couple of the most common reasons include IPN’s for orders that don’t exist in the store and third-party plugin or custom code conflicts.

IPN issues also appear with varied symptoms, from a renewal order not getting generated even though PayPal charged a customer to multiple renewal orders being created when PayPal only charged once or PayPal and Subscriptions disagreeing on how much the customer was / should have been charged.

This guide explained how to find information used to debug issues with WooCommerce Subscriptions the PayPal Standard’s IPN system.

IPN Processing Error Notice

When an error occurs while processing an IPN, WooCommerce Subscriptions will display a notice such as the following at the top of your store’s WordPress administration dashboard.

When this notice is displayed, it’s because the exact nature of the error cannot be automatically pinpointed. It will require further investigation by the support team to find the error and its causes. Additionally, to make sure it will not happen again, some form of intervention will likely be necessary to address the error.

When opening a ticket to report this error, there are a few pieces of information that will help the support team provide a smoother experience.

Please make sure to include a copy of the system status report. The system status report provides a snapshot of the site’s code and data, such as WooCommerce version and which plugins are installed. This type of information helps the support team to better understand the context of the error.

Finally, if some of the information below can be included, that can help to diagnose the error.

PayPal Subscription Details Page

PayPal provides information about subscriptions via the Subscription Details Page.

This page will look something like the picture below – PayPal change their interface from time-to-time and display different interfaces for different countries and account types, your page may appear differently.

A screenshot of this screen for a problematic subscription on your site would be very helpful. You can match them up by the profile ID or the customer.

This page holds information about what PayPal knows about the subscription. If there are differences between these details and the ones WooCommerce and Subscriptions have then that’s a clue.

PayPal Profile Status History page

Found by clicking View History button on the subscription page (near the top, under Subscription details). It looks similar to this:

When Subscriptions sends any data to PayPal, it will be recorded here. When it was created, when it was suspended or reactivated, when it was cancelled. If Subscriptions claims that it suspended the subscription, but PayPal did not register that change, that’s a clue.

IPN History for Problematic Subscriptions

PayPal keeps a record of IPN messages. These are also accessible via your PayPal account. These can be very valuable when diagnosing IPN errors. For example, if the was retried IPN, we’ll see that so we know the retries might cause multiple orders to be created, but something’s wrong because it had to retry.

To find the IPN history:

• Search by profile ID for the last payment transaction on this page (History > Find a transaction):
• View the transaction details and get the ID from there: 
• Put the ID into the IPN History screen to search: 
• Click on the message ID link, and grab that screenshot too:

These are all information we’ll need alongside the usual WooCommerce ticket requirements: System Status Report, FTP details, and sometimes database access details.

The post Subscriptions PayPal IPN Issues first appeared on CODIBU.

Some of these hooks had dynamic names, i.e. actions/filters where we don’t know what the hook actually is at run-time because it includes a payment gateway ID or another piece of dynamic data we don’t know in advance. Because of this, there was no choice but to either break backwards compatibility completely for those hooks (which would be severe in the case of scheduled subscription payment hooks) or add a small function to the 'all' hook to check if it’s a hook we have deprecated and maintain backwards compatibility.

The latter option was chosen as far better, but it may cause performance issues on some sites. We have, however, attempted to mitigate performance issues and also made sure there is a way to remove this code if your site is negatively affected and you know you have no deprecated code running on your site.

Mitigating performance issues

Functions attached to 'all', while running many times each request, are minor. They simply check the name of the hook to see if they start with 13 known hook prefixes.

This was done to mitigate any major performance impact on your site. However, depending on the number of plugins running on your site, you may find that running this tiny piece of logic on all hooks markedly reduces site performance. If this is the case, consider removing deprecated handling as outlined below.

Removing deprecated hook handling

If you know your site is not running outdated code, you can avoid having to load both this and other depreciation handling code to improve performance with Subscriptions 2.0.

The snippet below tells Subscriptions not to load deprecated handlers, including classes that attach to the 'all' hook to handle dynamic hooks:

This snippet can also be downloaded and installed as a plugin.

Warning

You must be certain that no third-party or custom code is running on your site that is dependent on deprecated hooks before disabling this deprecated hook handling. Disabling will break backwards compatibility with all old hooks and can, among other things:

• Prevent recurring payments being processed
• Break synchronization of subscription status between the payment gateway and store
• Break updating of a failing payment method

List of Deprecated Hooks

This gist provides a complete list of deprecated hooks, and their new counterpart, formatted as PHP arrays. The new hook is listed as the array key, and the deprecated hook as the value or values.

The post Subscriptions 2.0 Deprecated Hooks & Query Monitor Warning first appeared on CODIBU.

There are a number of updates you can make to your gateway extension’s code to support these changes and avoid deprecated notices on your customer’s sites.

If you have not already, you should read the What’s New in Subscriptions v2.0 document and Overview of Subscriptions v2.0 Architectural Changes before continuing with this document.

Items to Update

To be fully compatible with Subscriptions v2.0, you need to:

• update use of deprecated hooks
• update the location of your meta data
• add support for multiple subscriptions
• add support for admin payment method changes
• update customer facing change payment method support (if you already support it)
• use renewal orders for processing renewal payments
• make sure relevant meta data is copied from the original order to the subscription for existing orders/subscriptions on upgrade. All post meta on the original order will be copied by default by the Subscriptions upgrader, so you only need to copy meta data stored elsewhere or exclude post meta data you do not want copied, if any

Example Code: Simplify Commerce

For example code of the patches required to make a token based payment gateway fully compatible with Subscriptions v2.0, see the Simplify Commerce Subscriptions v2.0 Pull Request for WooCommerce Core.

This pull request includes annotated commits for all of the patches required by a token based payment gateway to be fully compatible with Subscriptions v2.0.

Store Meta Data on the Subscription not the Original Order

As discussed in the overview of Subscriptions v2.0’s Architectural Changes, a subscription’s meta data is no longer stored against the order created to record the purchase of that subscription. It is now stored on a separate 'shop_subscription' post type.

As a result, if your gateway stores payment related meta data, like credit card or customer tokens, it should store this against the subscription or subscriptions created during checkout and not the original order (as was previously the case).

This is also essential for adding support for the new Admin Payment Method Changes feature.

As Subscriptions will copy all post meta data stored against the 'shop_subscription' post to renewal orders (i.e. 'shop_order' posts), your gateway’s meta data will be copied to renewal orders and you can then access it on the renewal order to process the renewal payments via the 'woocommerce_scheduled_subscription_payment_{$gateway_id}' hook.

A note on upgrading: as mentioned above, all post meta on the original order will be copied by default by the Subscriptions upgrader. So migrating your code to use post meta on the subscription will work for both old and new subscriptions.

Update Deprecated Hooks

A number of hooks have been deprecated in Subscriptions v2.0, mainly due to the architectural changes.

Specifically, the following hooks have been changed in order to change the parameters passed to callbacks:

• 'scheduled_subscription_payment_{$gateway_id} has been replaced with 'woocommerce_scheduled_subscription_payment_{$gateway_id}'
• 'woocommerce_my_subscriptions_recurring_payment_method' has been replaced with 'woocommerce_my_subscriptions_payment_method'
• 'woocommerce_subscriptions_renewal_order_meta_query' has been replaced with 'wcs_resubscribe_order_created' in the case of what were previously called “parent” renewal orders and 'wcs_renewal_order_created' for orders that were previously called “child” renewal orders; and
• 'woocommerce_subscriptions_changed_failing_payment_method_{$gateway_id}' has been replaced with 'woocommerce_subscription_failing_payment_method_updated_{$gateway_id}'

You should update your use of these deprecated hooks to avoid notices and also take advantage of the extra features provided by receiving a WC_Subscription as a parameter.

Hook for Recurring Payment Method Display

By default, Subscriptions displays your payment gateway extension’s name as the payment method for a subscription; however, Subscriptions also provides an API for displaying a custom label. This can be used to provide a gateway specific and more descriptive label on the payment method. For example, the Stripe extension uses it to display the last 4 digits of the credit card used for recurring payments instead of simply Credit Card.

In Subscriptions v1.5, the filter for displaying a custom label was: 'woocommerce_my_subscriptions_recurring_payment_method'.

In Subscriptions v2.0, this has been changed to 'woocommerce_my_subscriptions_payment_method'.

The new filter passes the string displayed to describe the payment method (the same as the old filter), and then an instance of a WC_Subscription for which the string relates. This can be used to access meta data specific to that subscription.

Support for Multiple Subscriptions

Most modern payment gateways should be able to support Subscriptions v2.0’s new multiple subscriptions feature.

Specifically, if your payment gateway uses customer or credit card tokens for processing renewals, you will be able to support multiple subscriptions. Furthermore, if your payment gateway stores the meta data it uses to process automatic payments in post meta and/or user meta, adding support will be as simple as adding a 'multiple_subscriptions' value to your extension’s $supports property.

To learn more about how multiple subscriptions is implemented in Subscriptions v2.0 and to understand whether your payment gateway will be able to support it, refer to the overview of multiple subscriptions.

Support Admin Payment Method Changes

Subscriptions v2.0 introduces a new feature to allow store managers to change the payment method used on a subscription. To learn how to add support for this feature in your extension, refer to the Admin Change Payment Method Integration Guide.

Update Customer Facing Change Payment Method Support

Subscriptions v1.5 provided a customer facing process for changing the payment method.

Because it is now possible to store a subscription’s payment method meta data on the subscription instead of the original order, this process has been updated for v2.0.

To update your process, you need to:

1. declare support for the new feature, which is 'subscription_payment_method_change_customer': a new feature name has been chosen to both require an update and to differentiate between the new admin payment method change feature and the customer facing feature.
2. update your payment method’s meta data using the new 'woocommerce_subscription_failing_payment_method_updated_{$gateway_id}' hook, which passes your gateway the WC_Subscription object, instead of the old 'woocommerce_subscriptions_changed_failing_payment_method_{$gateway_id}' hook, which passed the WC_Order of the original purchase.

The code required to update Simplify Commerce can be seen in this commit to WooCommerce core on GitHub.

Use Renewal Order for Processing Scheduled Payment

As discussed in the overview of renewal order creation changes, Subscriptions v2.0 now creates the renewal order for recurring payment before triggering the scheduled subscription payment hook.

This makes it possible to use the same code for processing an initial payment as for processing a recurring payment (as the renewal order contains all essential information about the payment). It also makes it possible to record the transaction ID of the recurring payment on the renewal order by calling $renewal_order->payment_complete( $transaction_id ).

To use the renewal order for processing scheduled payments, update the code attached to the deprecated 'scheduled_subscription_payment_{$gateway_id}' action to use the new hook 'woocommerce_scheduled_subscription_renewal_{$gateway_id}' instead.

This hook will pass callbacks:

1. the amount to charge (the same as the first parameter in Subscriptions v1.5)
2. an instance of a WC_Order, which represents the pending renewal order for this payment

You can also process the renewal payment without having to worry about the associated subscription by calling $order->payment_complete( $transaction_id ) where $order is the renewal order, just as you would with a normal payment.

A Note on Tokens and Renewal Order Meta Data

You may be wondering why the 'woocommerce_scheduled_subscription_payment_{$gateway_id}' only passes callbacks the amount and a single order as a parameter, but not the WC_Subscription for which the order relates. This is to lay the foundation for batch processing renewal payments for multiple subscriptions in a single order. More generally, it also helps provide APIs that only require an understanding of WooCommerce primatives, like WC_Order, instead of Subscriptions specific objects, like WC_Subscription.

When a renewal order is generated, via wcs_create_renewal_order(), Subscriptions copies all post meta data rows stored against the 'shop_subscription' object to the new renewal order object. It is possible for extensions to opt-out their data from this process using the 'wcs_renewal_order_meta' or 'wcs_renewal_order_meta_query' hook, but it is recommended that you let your payment gateway’s token data be copied to renewal orders. This makes it possible to use only the parameters passed along with 'woocommerce_scheduled_subscription_payment_{$gateway_id}', instead of also having to use wcs_get_subscription_for_renewal_order() to access the data on the subscription.

Handling $0 Renewals

You may also (optionally) remove any code your gateway has to process $0 renewal orders/payments. Subscriptions v1.5 still called the payment gateway hook if a $0 amount was due; however, in v2.0, it no longer involves the payment gateway, and instead generates the order and processes it internally.

Test Cases

After you have updated your integration, you can confirm everything is working by running through all of the following test cases using your payment gateway as the payment method.

Tests for Subscriptions v1.5 and v2.0

• checkout with only a simple product in the cart
• checkout with only a simple subscription product in the cart
• checkout with only a simple subscription product with a sign-up fee in the cart
• checkout with only a simple subscription product with a free trial in the cart
• checkout with only a simple subscription product with a sign-up fee and free trial in the cart
• checkout with only a simple subscription product synchronized to a day in the future in the cart
• checkout with only a simple subscription product with a sign-up fee and synchronized to a day in the future in the cart
• checkout with a simple product and simple subscription product in the cart
• trigger an automatic renewal for a subscription with valid payment gateway meta data to test automatic payment success
• trigger an automatic renewal for a subscription with invalid payment gateway meta data to test automatic payment failure
• complete the manual payment process for the failed renewal and confirm that payment gateway meta data is updated correctly. Then trigger an automatic renewal after changing the payment method to ensure future renewals use the new payment gateway meta data
• test the Change Payment Method process on a subscription and confirm that payment gateway meta data is updated correctly. Then trigger an automatic renewal to ensure future renewals use the new payment gateway meta data.

Test for Subscriptions v2.0 Specific Functionality

• checkout with multiple simple subscription products with different billing periods in the cart (e.g. one subscription product renewing weekly and another renewing monthly)
• trigger an automatic renewal with working payment gateway meta data for a subscription with multiple simple subscription product line items
• checkout with a simple product and multiple simple subscription products in the cart
• (optional) if you added support for administrator payment method changes, change payment method on a subscription from the admin then trigger an automatic renewal to ensure future renewals use the new payment gateway meta data.

The post Subscriptions v2.0: Payment Gateway Upgrade Guide first appeared on CODIBU.