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.

This script will create a new 'shop_subscription' post for each subscription on the site and then migrate all meta data relating to a subscription from the original order used to purchase the subscription to the new 'shop_subscription' post.

As seen the interface screenshot below, this script upgrades all subscriptions on the site in batches of 50 subscriptions at a time via series of synchronous Ajax requests to avoid memory exhaustion or script timeouts on stores with large numbers of subscriptions.

The data migrated includes:

• Billing schedule, including recurring interval and period, and trial end, next payment and end dates
• Subscription product line item
• Download permissions for the subscription product
• Order notes which contain any of the words subscription, recurring or renewal, as these are deemed to relate to the subscription not the original order
• Recurring tax, shipping and coupon order items and their associated meta data
• Switch, renewal and resubscribe meta data linking switch, renewal and resubscribe orders to the new subscription instead of the original order
• All post meta data not excluding with the 'wcs_upgrade_subscription_meta_to_copy' filter

Specific details of the data upgraded during the process can be seen in the WCS_Upgrade_2_0 class found in /includes/upgrades/class-wcs-upgrade-2-0.php file.

Excluding of Post Meta Data

Subscriptions uses an opt-out approach to migrating meta data to the new subscriptions during the upgrade. This is to achieve compatibility by default rather than requiring all developers to opt-in to have their code be compatible.

This is especially important for payment gateways which historically attached billing data, like customer tokens, to the original order. It ensures that this data is copied to the new subscription, which is where we recommend developers store it from v2.0 onwards.

It also allows the data to be relied upon to exist on the subscription for all old and new subscriptions, instead of just new subscriptions. As well as saving if/else statements, this ensures the payment method meta data can be changed by store managers on both old and new subscriptions if the extension supports this new feature.

However, if your extension attaches meta data to an order that should not be copied to 'shop_subscription' objects, you can use the 'wcs_upgrade_subscription_meta_to_copy' filter to prevent it being copied to the subscription. An example of the kind of data may not need to be copied to new subscriptions is a shipment tracking number specific to the original order.

The example below shows how to make sure meta data with the meta key of '_my_shipment_tracking_code' is not copied to new subscription on upgrade.

function eg_do_not_copy_tracking_code( $order_meta ) {
    if ( isset( $order_meta ) ) {
        unset( $order_meta['_my_shipment_tracking_code'] );
    }
    return $order_meta;
}
add_filter( 'wcs_upgrade_subscription_meta_to_copy', 'eg_do_not_cop

The post Subscriptions v2.0: Database Upgrade Process for v1.5 to v2.0 first appeared on CODIBU.

This was the most important change in Subscriptions’ code base since it was first developed more than 3 years prior to the version 2.0 release. It was also the first time a major breaking change to Subscriptions’ code base was introduced.

While all reasonable efforts were undertaken to maintain backward compatibility with API functions and existing actions/filters, custom code written against the Subscriptions v1.5 code base may not be compatible with the v2.0. In particular, if code accesses a subscription’s meta data directly in the database, or against order (i.e. WC_Order) or cart (i.e. WC()->cart or WC_Cart) objects, it will most likely be broken.

This guide explains the history behind the old architecture and the reason changes were necessary. It then provides an overview of the changes to help understand how to update code written to integrate with Subscriptions.

If you have not already, you may wish to read the What’s New in Subscriptions v2.0 and Store Manager Guide to Multiple Subscriptions documents to get a non-technical overview of the changes introduced by Subscriptions v2.0.

A History of Subscriptions

Almost 3 years from the time of writing, Subscriptions v1.0 was first being designed. It was being created to achieve one simple goal – connect WooCommerce with PayPal Standard’s Subscriptions.

Because PayPal offered off-site payment processing and subscription storage, little consideration was given to how to store and manage a subscription after it was purchased within WooCommerce. The most important aspect of the design was how to create a subscription product in WooCommerce and then how to pass the details of that product to PayPal on checkout. It’s no coincidence that the product components of Subscriptions’ architecture are not changing in v2.0. A subscription is still a custom product type that extends from a base WooCommerce product class.

However, because of the focus on PayPal and the features it provided, the original architecture had some major short-comings:

1. it was not possible to purchase multiple different subscription products on different billing schedules in the same transaction. PayPal requires a customer to sign up for each subscription individually, so to purchase an annual, monthly and weekly subscription in the same transaction and use PayPal as the payment method, the customer would need to complete checkout with PayPal 3 times.
2. Subscriptions only needed to know the PayPal Profile ID for the subscription and handle IPN messages in order to handle recurring payments. Because PayPal took care of all of this, the method by which subscription meta data (such as recurring totals, completed renewal payments etc.) were stored in WooCommerce was an afterthought. It was such an after thought, that renewal orders, now the backbone of a subscriptions record keeping and inventory management, did not exist until version v1.2.
3. subscription management within the store, like modifying a subscription’s billing schedule, shipping, taxes or line items was not possible, because PayPal didn’t allow any of these details to be changed. As a result, when interfaces for these tasks were introduced in later versions of Subscriptions, they were also an afterthought that needed to be retrofitted to the original architecture.

Subscriptions v1.5 Architecture

v1.5 Data Storage – the Order

Because Subscriptions was first designed to simply link an order in a WooCommerce store with PayPal, Subscriptions v1.5 stored all meta data relating to a subscription on the original order created to record the purchase of a subscription product.

Because much of a subscription’s data was not even stored in v1.0, this meant that as newer versions of Subscriptions required new meta data to add new features with other payment gateways (like changing payment method or billing/shipping address), this data was retrofitted to the order. As a result, data was often stored in unexpected and disjointed places.

For example, a subscription’s data in v1.5 was stored in the following database tables:

• wp_postmeta: some values designed to mirror the original order’s meta data on the subscription were stored in the post meta table against the original order, like _recurring_payment_method (which mirrored the original order’s _payment_method and was the payment method used to process renewals) or _recurring_order_total (which mirrored the original order’s _order_total and was the amount charged for renewal payments)
• wp_woocommerce_order_items: some values mirroring the original order’s items were stored in the order item table, like recurring_tax item/s (which mirrored the original order’s tax item/s for recurring amounts) or recurring_shipping item/s (which mirrored the original order’s shipping item/s for recurring amounts)
• wp_woocommerce_order_itemmeta: some values relating to the subscription product’s billing terms were stored in the order item meta table against the subscription product’s line item. For example, a subscription’s billing schedule (_subscription_period and _subscription_interval), status (_subscription_status) and important dates (_subscription_start_date, _subscription_expiry_date, _subscription_trial_expiry_date and _subscription_completed_payments) were all stored in the order item meta table.

This storage system was:

• inefficient: querying subscriptions almost always required a number of JOIN statements and queries on columns of a generic varchar type (the type used for meta values). For example, a query to get subscriptions by start date required joining 3 tables: wp_posts, wp_woocommerce_order_items and wp_woocommerce_order_itemmeta to search for a MySQL formatted date stored as a varchar. This ultimately led to serious scaling issues once a store started to enjoy more than 20,000 subscribers. In v2.0, the same query is on a single table (wp_posts) in a column with a more accurate type (datetime) and it uses a schema proven to scale to hundreds of thousands of rows.
• cumbersome: to find out any details on a subscription, you needed to know the order ID and often either the user ID and/or product ID for that subscription. Each subscription did not have a simple, unique ID which could be used to access it and pass around its data.
• unintuitive: as a subscription has evolved into an important object, new developers coming to Subscriptions now expect to find a discrete subscription object, not a collection of data attached to an order.
• repetitive: because this schema was completely unique to Subscriptions, it was not possible to take advantage of code already written in WordPress or WooCommerce for querying data. This makes simple feature requests, like improved reporting, difficult to implement because it requires custom database queries compared with using well known WordPress API functions like get_posts().

v1.5 Data Structure – the Array

As a subscription had very little data in v1.0, and that data rarely needed to be accessed or modified, the data structure chosen for accessing a subscription’s details at the application level was the most basic object available: an array.

As new versions of Subscriptions began to provide features for modifying a subscription, the array structure was maintained and separate functions were implemented to act on the subscription’s data, including the most primitive WordPress functions for acting on data like update_post_meta() or subscription specific functions like WC_Subscriptions_Manager::update_subscription().

Because an array can not have methods, this was the only approach available, despite native methods on the object offering a much more natural approach (e.g. $subscription->update_status()) and also providing many of the benefits of object oriented programming, like abstraction and encapsulation.

Evolution of the WooCommerce Ecosystem

In addition to the issues outlined above with the existing data storage and structure used for a subscription, the payment gateway and WooCommerce landscape evolved dramatically in the time since Subscriptions 1.0 was designed.

Uptake of Modern Payment Gateway APIs

In the 3 years since first designing Subscriptions, modern payment gateways that provide credit card tokens, like Stripe and Authorize.net CIM, have become more available to non-US markets and easier to access by non-technical store owners. This development has created an opportunity for Subscriptions’ feature set to be designed for these modern, more flexible payment methods, rather than the out-dated APIs offered by PayPal Standard.

Feedback on the Subscriptions feature set has consistently demanded more control over subscription data from within the WooCommerce store. This is possible with these modern payment gateways (but not PayPal Standard).

With Subscriptions 2.0 therefore, there was an opportunity and a need to design a system for these gateways that provides more control to store owners. Fortunately, there was also a recent development in WooCommerce that made such a change possible.

WooCommerce v2.2 and Custom Order Types

WooCommerce v2.2 quietly introduced a new API that could have great implications for plugins like Subscriptions – the custom order types API.

This API allows for more than just the standard simple order type to exist in a WooCommerce store.

An order is WooCommerce’s snapshot of history. In the case of a simple order, it is used to record a purchase transaction. In the case of a refund, it records the return of some or all of an order’s amount to the customer.

Unlike an order, a subscription is not a record of what has happened; instead, it is an agreement for what should happen. However, an order’s meta data, like customer billing and shipping details, product line items, taxes, fees and totals perfectly align with the details required for such an agreement. Therefore, a custom order type is the perfect data store for a subscription.

Store Manager Feedback

The final and most important driving force behind the change was the same factor that drives all of development on Subscriptions – customer feedback.

In addition to technical and market changes, our understanding of what store managers expect from a subscription management plugin evolved in the 3 years since releasing version 1.0.

Although no store manager has ever asked for a subscription to be stored as a custom order type, to support the numerous and diverse requests for all manner of features to be built on top of Subscriptions, the architecture needed to evolve. Many requested features, like upgrades/downgrades, updating payment method, changing shipping address, were implemented, painstakingly in some cases, on the Subscriptions 1.5 architecture.

However, many features could not be feasibly implemented with that architecture, such as the ability for customers to purchase different subscription products in a single transaction. Even simple requests, like gifting subscriptions, improved reporting or having shipping charged only on the initial order were extremely difficult to achieve with the v1.5 data scheme and structure.

The new architecture consolidates 3 years of feedback into a design that can support every feature request and behaviour change we’ve received in that time. Even if these do not make it into Subscriptions core, it will be possible to write them as mini-extensions with significantly less developer time than previously required.

Introducing the Subscription Order Type

The backbone of the v2.0 changes is a new subscription order type.

In much the same way as an order is stored as a 'shop_order' post type and instantiated as an instance of a WC_Order class, the subscription order type consists of a 'shop_subscription' post type and WC_Subscription class.

The 'shop_subscription' Post Type

The 'shop_subscription' post type is a WordPress custom post type created by wc_register_order_type() to be used for the storage of subscription data.

As this post type is an extension of the 'shop_order' post type, a subscription’s meta is stored in the same locations as an order’s data, making it possible for developers to learn where an order’s data is stored, and then instantly understand where a subscription’s data will be stored. For example, after being purchased in an order, a subscription product becomes a line item on both that order and a subscription, meaning its data is consistently stored as a line_item in wp_woocommerce_order_items table for both the 'shop_order' and 'shop_subscription'.

The WC_Subscription Class

The WC_Subscription class extends WC_Order to provide an object for interacting with a subscription’s data.

The object inherits all of the properties and methods of the WC_Order class (which also includes those of its parent – WC_Abstract_Order). These properties and methods make it significantly more intuitive to work with a subscription’s data. For example, in v2.0, changing a subscription’s status can be done with the WC_Abstract_Order->update_status() method (e.g. $subscription->update_status().

In addition, the WC_Subscription class also adds new properties for storing a subscription’s meta data, mainly relating to billing schedule and important dates, like the next payment date, and new methods for interacting with this data, like WC_Subscription->update_dates().

Benefits of the Subscription Order Type

The primary benefits of the subscription order type are:

• WordPress’s post list table: as a subscription is now a custom post type, the custom list table used on the Manage Subscriptions screen has been replaced by a WordPress post list table. This saved hundreds of lines of code and helps provide better future proofing of the list table for updates to WordPress and WooCommerce markup and CSS.
• Scalable storage: now that a subscription’s data is stored in the same way as other WordPress custom post types and WooCommerce orders, Subscriptions can take advantage of trusted API functions, like get_posts(), to work with subscription data and be confident that queries will scale.
• DRY: by using a custom order type, Subscriptions can take advantage of WooCommerce code to add new features more quickly and with less code. An example of this in v2.0, beyond the obvious example of extending WC_Order, is the introduction of API endpoints for subscriptions. This is done by introducing a new WC_API_Subscriptions class which extends WC_API_Orders and benefits from much of the code in that class.
• Learn once: developers familiar with working with WooCommerce’s orders can now transfer that knowledge entirely to working with subscriptions. Instead of having to learn an entirely new set of API functions and database schema, developers now need to only learn where the extra meta data is stored and how to access it.

Implications of the Subscription Order Type

By changing the database schema and application level data structure of a subscription, code handling everything from the initial purchase through to renewal and management of a subscription has had to be updated.

This is because old functions expected some combination of an order ID or WC_Order, subscription key (consisting of the order ID and product ID, not a unique integer ID for that object), user ID and/or product ID. Similarly, the hooks used for existing actions and filters would pass this data to callbacks; where as in v2.0, those callbacks need the WC_Subscriptions or ID of the 'shop_subscription' to take advantage of the new architecture.

Backward Compatibility

All reasonable steps have been taken to ensure existing functions and actions/filters will continue to work. However, use of deprecated functions, actions and filters will throw deprecated notices and they will be removed in future versions.

Furthermore, some hooks may have been called on events which no longer occur, like creating a pending subscription by adding an order added via the administration screen.

Finally, any code directly querying the database to read or write subscription data will no longer be compatible with the new schema in Subscriptions v2.0.

Other Changes

This guide focused on the introduction of the 'shop_subscription' post type and corresponding WC_Subscription class; however, there are a number of other notable changes introduced in Subscriptions v2.0 that related to developers.

Renewal Order Relationship Change

In Subscriptions v1.5, a subscription was connected to a renewal order using the renewal order’s post_parent column in the wp_posts database table.

Specifically, the post_parent was set to the post ID of the original order used to purchase a subscription (because a subscription in v1.5 did not have its own unique ID).

In v2.0, this relation was changed to use post meta on the subscription post type. A meta_key of _subscription_renewal storing a meta_value of the subscription’s post ID is now used to record this relationship.

This change makes it possible to have a many-to-one relationship between subscriptions and renewal orders. That is to say, a single renewal order can now be related to multiple subscriptions; where as in v1.5, a renewal order could only relate to a single subscription. Although this new capability isn’t being used in any meaningful way with the release of Subscriptions v2.0, it was introduced with v2.0 because the relationship needed to change to use the ID of a 'shop_subscription' post, not the ID of a 'shop_order' post.

As the relationship needed to change in v2.0 anyway, this change was implemented now to avoid another breaking change in the future version.

The many-to-one relationship makes it possible to implement advanced features in the future, like batch processing renewal payments for different subscriptions in a single renewal order. Such a feature would save store owners fees as most payment gateways charge a per transaction fee, like Stripe’s $0.20.

Renewal Order Creation Before Scheduled Payment Hook

Subscriptions v1.0 did not create renewal orders because PayPal recorded transaction details and sent store owners and customers the details of those transactions.

Accordingly, when renewal orders were introduced in version v1.2, renewal order creation was retrofitted to the existing codebase and therefore, renewal orders were only created after the payment gateway processed the payment.

This design had a few significant drawbacks:

• payment gateways had to use special Subscription API functions and write special code for handling subscription renewal payments, instead of being able to use code written for WooCommerce’s order object that worked for all payments.
• when WooCommerce v2.2 introduced the _transaction_id API for storing a payment gateway’s transaction on a renewal order, it was not possible for payment gateways to add the transaction ID for renewal orders without hacks.
• if an unrecoverable error occurred when attempting to process the renewal payment, the renewal order would not be created. This also meant sites which had an unrecoverable error needed to run special code in order to generate missing orders.

Because of these drawbacks, Subscriptions v2.0 changes the flow of operations to create the renewal order before the scheduled subscription payment hook is triggered.

To learn how to take advantage of this change and use the renewal order for processing renewal payments with your payment gateway extension/s, refer to the Payment Gateway Upgrade Guide.

Changes to the Switching Process

If you are not familiar with the switching feature of Subscriptions (i.e. upgrading/downgrading), please read the switching guide before continuing with this section.

In Subscriptions v1.5, switching a subscription from one variation or grouped product to another always created a new subscription and set the status of the old subscription to switched. This was to ensure compatibility of the switching feature with PayPal, and to always avoid rewriting history and changing subscription related meta data on the original order used to purchase the subscription.

However, due to the architectural changes in v2.0, it is now possible to simply change the details of the subscription object without losing the history of the original order.

Furthermore, because a subscription may now contain multiple line items, switching needed to be updated to be per item instead of per subscription.

In v2.0, the switching process now:

• removes the line item from the old subscription
• adds the new item as a line item on the existing 'shop_subscription' if the new item is:
  • on the same billing schedule as the old subscription; or
  • on a different billing schedule, but is the only line item on the subscription, and therefore, the subscription’s billing schedule can be changed.
• creates a new 'shop_subscription' if the new item is on a different billing schedule and the old subscription had more than one line item.

The switching process still uses the cart and checkout as it did in v1.5. A switch order is also still created to record the switch. This order is created regardless of whether proration is enabled and a prorated amount is charged for the switch or the switching cost is $0. Multiple switches can also be completed at the same time, for multiple line items on the same or different subscriptions.

New Pending Cancellation Status

Subscriptions v2.0 introduced a new subscription status: Pending Cancellation.

This status, internally stored as wc-pending-cancel (because wc-pending-cancellation is too long for the post_status column), is given to a subscription to signify that the customer or store manager has cancelled the subscription, but the customer is still entitled to a pre-paid term.

The status will be applied to a subscription whenever a customer or store manage cancels a subscription. It is set automatically when calling WC_Subscription::cancel_order(), but not when calling WC_Susbcription::update_status() to provide an API for developers that immediately transitions a subscription to cancelled status (the wc-cancelled status).

Prior to Subscriptions v2.0, the pre-paid term was signified only by an action triggered at the end of the pre-paid term ('subscription_end_of_prepaid_term'). It was left up to developers to use it as required, and was not used internally by Subscriptions.

Example of Pending Cancellation

If a customer buys a monthly subscription on the 1st January, then cancels the subscription on 15th January, in Subscriptions v1.5, its status would immediately be changed to wc-cancelled, the customer’s role would immediately be transitioned to the default inactive role and then on the 1st February, a 'subscription_end_of_prepaid_term' hook would be triggered.

With v2.0, that subscription’s status will be immediately set to wc-pending-cancel and the customer will keep the default active subscriber role. On the 1st February, the subscription’s status will be changed to wc-cancelled and the customer’s role will be changed to the inactive role. The end of prepaid term hook will also be triggered.

Store Manager Guide to v2.0 Changes

A summary of all the changes in relation to how a store manager interacts with the Subscriptions extension can also be found in the Overview of Subscriptions v2.0’s Changes document.

The post Subscriptions v2.0 Architectural Changes first appeared on CODIBU.

Subscriptions provides a comprehensive API and takes care of much of the subscription management automatically – you just need to add payment processing. This guide outlines the necessary steps for integrating a payment gateway with WooCommerce Subscriptions.

There are 6 steps to add subscription support:

1. Register Support for Subscriptions
2. Process Subscription Sign-ups
3. Manage Subscriptions
4. Process Failed Payments
5. Handling Recurring Payment Method Changes
6. Show your Support

Before continuing with this guide, you should have read the Subscriptions’ API overview. You should also have an in-depth understanding of the WooCommerce Payment Gateway API.

Need to upgrade a payment gateway for WooCommerce Subscriptions version 2.0? Check out the Payment Gateway Upgrade Guide.

Step 1: Registering Support for Subscriptions

When an order contains a subscription product, the Subscriptions extension filters the available payment gateways to display only those that support recurring payments.

Your gateway must register its support for subscriptions using the WC_Payment_Gateway::supports() API (in WooCommerce 1.5.7 and newer). This is done by setting the supports property of your gateway to an array containing ‘subscriptions’ (and ‘products’ if your gateway also supports product purchases).

For example, the __construct() function of your gateway class should include a line like the following:

class WC_Awesome_Gateway extends WC_Payment_Gateway {
     function __construct() {
          ...
          $this->supports = array( 'subscriptions', 'products' );
          ...
     }
     ...
}

Now, whenever an order contains a subscription, if your gateway is enabled, it will be displayed as a payment option on the checkout page.

Step 1.1: Registering Support for Subscription Management Features

If your payment gateway supports subscription management functions, like cancelling or suspending a subscription, you should also notify Subscriptions that your gateway can handle these functions.

There are a variety of functions Subscriptions will implement if a payment gateway support it, including:

• subscription cancellation
• subscription suspension
• subscription reactivation (after suspending a subscription)
• subscription amount changes (recurring amount can be changed for the subscription)
• subscription date changes (next payment date can be changed for the subscription)

To register your gateways support for these features, you add the relevant flag to your gateway’s supports property.

This is an example for a gateway which supports all features:

class WC_Awesome_Gateway extends WC_Payment_Gateway {
     function __construct() {
          ...
          $this->supports = array( 
               'products', 
               'subscriptions',
               'subscription_cancellation', 
               'subscription_suspension', 
               'subscription_reactivation',
               'subscription_amount_changes',
               'subscription_date_changes',
               'subscription_payment_method_change'
               'subscription_payment_method_change_customer',
               'subscription_payment_method_change_admin',
               'multiple_subscriptions',
          );
          ...
     }

Note: If your payment gateway extension is using token based billing and relying on Subscriptions’ scheduled payment hooks to charge each recurring payment, it can support all of the available features, so add a flag for every feature.

Step 2: Processing a Subscription Sign-Up

Like processing payment for a product, your payment gateway extension will need to process a subscription sign-up in its process_payment() function.

Depending on how you gateway processes subscriptions, you may need to know any of the initial payment amount, the subscription’s sign-up fee, price per period, billing period and duration at outset of the subscription.

To obtain these details for an order containing a subscription, use the WC_Subscriptions_Order class methods.

Initial Payment

If your payment gateway requires one upfront amount for the beginning of the subscription, you can use

<?php WC_Subscriptions_Order::get_total_initial_payment( $order ) ?>

Where $order is a WC_Order object.

For more details, see the full total initial payment function reference.

Price Per Period

If your payment gateway needs to know when creating the subscription how much to charge for each individual billing period, you can use:

<?php WC_Subscriptions_Order::get_price_per_period( $order ) ?>

For more details, see the full price per period function reference.

Sign-up Fee

If your payment gateway needs a distinct sign-up fee amount for an order, you can call:

<?php WC_Subscriptions_Order::get_sign_up_fee( $order ) ?>

For more details, see the full sign up fee function reference.

Billing Period

To get the subscription period for an order, call:

<?php WC_Subscriptions_Order::get_subscription_period( $order ) ?>

For more details, see the full subscriptions period function reference.

Free Trial Period

Payment gateways typically require one of two methods for setting up a free trial

1. Passing the free trial period and length, like PayPal; or
2. Setting the start date for the subscription, like WorldPay.

To use the first method, get a subscriptions trial details with the following two functions:

<?php 

WC_Subscriptions_Order::get_subscription_trial_period( $order );

WC_Subscriptions_Order::get_subscription_trial_length( $order );

?>

To use the second method and set the start date, use the following function:

<?php WC_Subscriptions_Product::get_trial_expiration_date( $product_id, $order_start_date ); ?>

Subscription Length

To get the subscription duration for an order, call:

<?php WC_Subscriptions_Order::get_subscription_length( $order ) ?>

For more details, see the full subscriptions length function reference.

Putting it all Together

The paypal_standard_subscription_args() function within the bundled WC_PayPal_Standard_Subscriptions class provides an example of accessing subscription details and combining them into a payment gateway request.

extract( self::get_order_id_and_key( $paypal_args ) );

if ( WC_Subscriptions_Order::order_contains_subscription( $order_id ) ) {

    $order = new WC_Order( $order_id );

    $order_items = $order->get_items();

    // Only one subscription allowed in the cart when PayPal Standard is active
    $product = $order->get_product_from_item( $order_items[0] );

    // It's a subscription
    $paypal_args['cmd'] = '_xclick-subscriptions';

    if ( count( $order->get_items() ) > 1 ) {

        foreach ( $order->get_items() as $item ) {
            if ( $item['qty'] > 1 )
                $item_names[] = $item['qty'] . ' x ' . $item['name'];
            else if ( $item['qty'] > 0 )
                $item_names[] = $item['name'];
        }

        $paypal_args['item_name'] = sprintf( __( 'Order %s', WC_Subscriptions::$text_domain ), $order->get_order_number() );

    } else {

        $paypal_args['item_name'] = $product->get_title();

    }

    $unconverted_periods = array(
        'billing_period' => WC_Subscriptions_Order::get_subscription_period( $order ),
        'trial_period'   => WC_Subscriptions_Order::get_subscription_trial_period( $order )
    );

    $converted_periods = array();

    // Convert period strings into PayPay's format
    foreach ( $unconverted_periods as $key => $period ) {
        switch( strtolower( $period ) ) {
            case 'day':
                $converted_periods[$key] = 'D';
                break;
            case 'week':
                $converted_periods[$key] = 'W';
                break;
            case 'year':
                $converted_periods[$key] = 'Y';
                break;
            case 'month':
            default:
                $converted_periods[$key] = 'M';
                break;
        }
    }

    $sign_up_fee = WC_Subscriptions_Order::get_sign_up_fee( $order );

    $initial_payment = WC_Subscriptions_Order::get_total_initial_payment( $order );

    $price_per_period = WC_Subscriptions_Order::get_recurring_total( $order );

    $subscription_interval = WC_Subscriptions_Order::get_subscription_interval( $order );

    $subscription_installments = WC_Subscriptions_Order::get_subscription_length( $order ) / $subscription_interval;

    $subscription_trial_length = WC_Subscriptions_Order::get_subscription_trial_length( $order );

    if ( $subscription_trial_length > 0 ) { // Specify a free trial period

        $paypal_args['a1'] = ( $sign_up_fee > 0 ) ? $sign_up_fee : 0; // Maybe add the sign up fee to the free trial period

        // Trial period length
        $paypal_args['p1'] = $subscription_trial_length;

        // Trial period
        $paypal_args['t1'] = $converted_periods['trial_period'];

    } elseif ( $sign_up_fee > 0 ) { // No trial period, so charge sign up fee and per period price for the first period

        if ( $subscription_installments == 1 )
            $param_number = 3;
        else
            $param_number = 1;

        $paypal_args['a'.$param_number] = $initial_payment;

        // Sign Up interval
        $paypal_args['p'.$param_number] = $subscription_interval;

        // Sign Up unit of duration
        $paypal_args['t'.$param_number] = $converted_periods['billing_period'];

    }

    // We have a recurring payment
    if ( ! isset( $param_number ) || $param_number == 1 ) {

        // Subscription price
        $paypal_args['a3'] = $price_per_period;

        // Subscription duration
        $paypal_args['p3'] = $subscription_interval;

        // Subscription period
        $paypal_args['t3'] = $converted_periods['billing_period'];

    }

    // Recurring payments
    if ( $subscription_installments == 1 || ( $sign_up_fee > 0 && $subscription_trial_length == 0 && $subscription_installments == 2 ) ) {

        // Non-recurring payments
        $paypal_args['src'] = 0;

    } else {

        $paypal_args['src'] = 1;

        if ( $subscription_installments > 0 ) {
            if ( $sign_up_fee > 0 && $subscription_trial_length == 0 ) // An initial period is being used to charge a sign-up fee
                $subscription_installments--;

            $paypal_args['srt'] = $subscription_installments;

        }
    }

    // Force return URL so that order description & instructions display
    $paypal_args['rm'] = 2;

}

Step 3: Subscription Management

After a subscription has been purchased with your extension, certain aspects of the subscription are managed automatically while others need to be managed by your gateway extension.

Order Status & Subscription Status Binding

Subscription status is bound to order status changes, so using the WooCommerce Payment Gateway API to set an order’s status will automatically set the status of a subscription. When an order status changes to processing or complete, a subscription purchased in the order is activated automatically. When an order is cancelled, refunded or marked as failed, the status of a subscription in that order will also be updated to cancelled or failed.

As a result, the bare minimum required to manage a subscription is to use the WooCommerce Payment Gateway API to manage an order’s status.

Subscription Payment & Status Management

There is no automatic handling of subscription payments. Either your gateway or your extension will need to handle these payments.

Recurring Payments Processed by the Gateway

If your payment gateway can automatically charge recurring payments, like PayPal, your extension can set up the subscription with the gateway and then use the WC_Subscriptions_Manager::process_subscription_payments_on_order() function to keep a record of each payment once the gateway has processed the payment.

If your payment gateway also manages the billing schedule, then you should also add the 'gateway_scheduled_payments' flag when registering support for Subscriptions. Not adding this flag can cause subscriptions to be incorrectly suspended when the gateway’s schedule does not precede the WooCommerce schedule.

Recurring Payments Processed by your Extension

Some payment gateways may have little or no support for recurring payments, but may allow you to charge a stored credit card. These gateways can still be integrated with WC Subscriptions to offer automatic recurring billing.

In fact, this is how the Stripe extension adds support for Subscriptions, even though the Stripe payment gateway can automatically charge recurring payments.

For each subscription, a 'scheduled_subscription_payment_{payment_gateway_id}' hook is fired whenever a payment is due for a specific gateway. This hook includes the amount due on the subscription (including outstanding payments, if any) as well as the order and product ID of the subscription. You can use this hook to process a subscription payment.

For example, the Stripe extension hooks its `scheduled_subscription_payment()` function to the 'scheduled_subscription_payment_stripe' hook to process the payment for each billing period:

function scheduled_subscription_payment( $amount_to_charge, $order, $product_id ) {

    $result = $this->process_subscription_payment( $order, $amount_to_charge );

    if ( is_wp_error( $result ) ) {
        WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order, $product_id );
    } else {
        WC_Subscriptions_Manager::process_subscription_payments_on_order( $order );
    }
}

This is also a good example of using the API functions for success and failure of the payment. More on failed payments later.

Charging payments on the 'scheduled_subscription_payment_{payment_gateway_id}' hook is only required if your gateway does not automatically charge recurring payments. However, this method can be used in-lieu of your payment gateways recurring billing solution because doing so has a few advantages:

1. You need less code to support subscription payments & subscription features like changing the next payment date because WC Subscriptions core will take care of all of this for you and you just need to hook to 'scheduled_subscription_payment_{payment_gateway_id}';
2. You have complete flexibility in the billing interval and period, e.g., some payment gateways, like Authorize.net ARB, only support a free trial period of the same billing period as the recurring payments, that is, Authorize.net ARB does not allow a 2 week trial period for a subscription billing every month;
3. You can support all Subscription features, regardless of those which your payment gateway’s recurring billing solution provides.

Activating a Subscription

<?php WC_Subscriptions_Manager::activate_subscriptions_for_order( $order ) ?&gt;

As the name suggests, the activate_subscriptions_for_order() can be used to mark all subscriptions in an order as active.

This function is fired automatically when an order’s status changes to completed or processing, so if you are correctly updating an order’s status, you do not need to call this function.

The function calls the WC_Subscriptions_Manager::activate_subscription() function for each subscription item in an order, which for now, will only be one item, but in future, this may be more than one item.

Cancelling a Subscription

If your gateway provides an API for cancelling a subscription (or you are manually charging recurring payments), you can add support for subscriptions to be cancelled in the store.

Just like registering support for subscriptions, you notify Subscriptions of your cancellation capability by including a flag in your extensions supports() property.

For example, the following is an excerpt from the PayPal Digital Goods gateway extension:

function __construct() { 

    // ...

    $this->supports = array( 'products', 'subscriptions', 'subscription_cancellation' );

    // ...
}

Note the 'subscription_cancellation' flag.

Including this flag will expose the Cancel action link on a subscription purchased with your gateway to store managers and subscribers. When this action link is clicked, Subscriptions will cancel the subscription in the store and you need to cancel the subscription with your gateway.

Subscriptions fires a 'cancelled_subscription' hook whenever a subscription is cancelled, but a better action to hook to use is 'woocommerce_subscription_cancelled_{payment_gateway_id}'. This hook passes the WC_Order object and WC_Product ID of the subscription product being cancelled. You can use these details to cancel the subscription with your gateway.

Cancellations at the Gateway

If a user can cancel a subscription with the payment gateway directly, you must reflect this change in the WooCommerce store by calling:

<?php WC_Subscriptions_Manager::cancel_subscriptions_for_order( $order ) ?>

This function is automatically called when an order’s status is changed to cancelled, failed or refunded order.

Internally, the function acts as a convenience wrapper function for the WC_Subscriptions_Manager::cancel_subscription() function. If you need to cancel just one subscription and no its associated order, you can call the cancel subscription function directly:

<?php WC_Subscriptions_Order::cancel_subscription( $user_id, $subscription_key ) ?>

Where $subscription_key is the key derived from the concatenation of the order ID, an underscore and the subscription product’s ID e.g. 153_12 for product ID 12 purchased on order 153.

Expiring a Subscription

The Subscriptions extension schedules a action to set a subscription’s status to expired when its expiration date arrives, so you do not need to manually expire a subscription.

However, if your payment gateway provides an expiration notification and you like the security of redundancy, you can call the WC_Subscriptions_Manager function directly.

To expire any subscriptions on an order call:

<?php WC_Subscriptions_Manager::expire_subscriptions_for_order( $order ) ?>

To expire an individual subscription call:

<?php WC_Subscriptions_Manager::expire_subscription( $user_id, $subscription_key ) ?>

If you’re charging recurring payments manually, you do not need to expire a subscription because the scheduled payment hooks will no longer fire once a subscriptions is cancelled.

Recording Payments

A subscription’s status does not change when each payment is received (except potentially for the first payment), however, Subscriptions provides an API to record payments. If your gateway provides a notification system, like the PayPal IPN, it’s a good idea to call the process_subscription_payments_on_order() function to keep a record of the payment on the order.

<?php WC_Subscriptions_Manager::process_subscription_payments_on_order( $order ) ?>

Recording Failed Payments

A subscription’s status does not change when a payment fails (unless the total number of failed payments exceeds the number the administrator has set for the store). However, you should still record failed payments. If your gateway provides a notification system, like the PayPal IPN, it’s a good idea to call the process_subscription_payment_failure_on_order() function to keep a record of the payment on the order.

<?php WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order ) ?>

Order API vs Individual Subscription API

You may have noticed a trend in the API. Subscriptions includes functions for operating both on an order and on an individual subscription. In most cases, you will find it easier to use the function that operates on an order. It is also better to operate on an order other than an individual subscription, because you will need to use less code within your extension.

Subscription Management Example

The process_paypal_ipn_request() function in the bundled WC_PayPal_Standard_Subscriptions class provides an example of manually, and redundantly calling subscription management functions.

This function is hooked to PayPal IPN requests and checks if the request relates to a subscription. The switch statement, included below, performs subscription management tasks for any subscription related transactions.

switch( $transaction_details['txn_type'] ) {
    case 'subscr_signup':

        // Store PayPal Details
        update_post_meta( $order_id, 'Payer PayPal address', $transaction_details['payer_email']);
        update_post_meta( $order_id, 'Payer PayPal first name', $transaction_details['first_name']);
        update_post_meta( $order_id, 'Payer PayPal last name', $transaction_details['last_name']);
        update_post_meta( $order_id, 'PayPal Subscriber ID', $transaction_details['subscr_id']);

        // Payment completed
        $order->add_order_note( __( 'IPN subscription sign up completed.', WC_Subscriptions::$text_domain ) );

        if ( self::$debug )
            self::$log->add( 'paypal', 'IPN subscription sign up completed for order ' . $order_id );

        break;

    case 'subscr_payment':

        if ( 'completed' == strtolower( $transaction_details['payment_status'] ) ) {
            // Store PayPal Details
            update_post_meta( $order_id, 'PayPal Transaction ID', $transaction_details['txn_id'] );
            update_post_meta( $order_id, 'Payer PayPal first name', $transaction_details['first_name'] );
            update_post_meta( $order_id, 'Payer PayPal last name', $transaction_details['last_name'] );
            update_post_meta( $order_id, 'PayPal Payment type', $transaction_details['payment_type'] ); 

            // Subscription Payment completed
            $order->add_order_note( __( 'IPN subscription payment completed.', WC_Subscriptions::$text_domain ) );

            if ( self::$debug ) 
                self::$log->add( 'paypal', 'IPN subscription payment completed for order ' . $order_id );

            $subscriptions_in_order = WC_Subscriptions_Order::get_recurring_items( $order );
            $subscription_item      = array_pop( $subscriptions_in_order );
            $subscription_key       = WC_Subscriptions_Manager::get_subscription_key( $order->id, $subscription_item['id'] );
            $subscription           = WC_Subscriptions_Manager::get_subscription( $subscription_key, $order->customer_user );

            // First payment on order, process payment & activate subscription
            if ( empty( $subscription['completed_payments'] ) ) {

                $order->payment_complete();

                WC_Subscriptions_Manager::activate_subscriptions_for_order( $order );

            } else {

                WC_Subscriptions_Manager::process_subscription_payments_on_order( $order );

            }

        } elseif ( 'failed' == strtolower( $transaction_details['payment_status'] ) ) {

            // Subscription Payment completed
            $order->add_order_note( __( 'IPN subscription payment failed.', WC_Subscriptions::$text_domain ) );

            if ( self::$debug ) 
                self::$log->add( 'paypal', 'IPN subscription payment failed for order ' . $order_id );

            WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order );

        } else {

            if ( self::$debug ) 
                self::$log->add( 'paypal', 'IPN subscription payment notification received for order ' . $order_id  . ' with status ' . $transaction_details['payment_status'] );

        }

        break;

    case 'subscr_cancel':

        if ( self::$debug ) 
            self::$log->add( 'paypal', 'IPN subscription cancelled for order ' . $order_id );

        // Subscription Payment completed
        $order->add_order_note( __( 'IPN subscription cancelled for order.', WC_Subscriptions::$text_domain ) );

        WC_Subscriptions_Manager::cancel_subscriptions_for_order( $order );

        break;

    case 'subscr_eot': // Subscription ended, either due to failed payments or expiration

        // PayPal fires the 'subscr_eot' notice immediately if a subscription is only for one billing period, so ignore the request when we only have one billing period
        if ( 1 != WC_Subscriptions_Order::get_subscription_length( $order ) ) {

            if ( self::$debug ) 
                self::$log->add( 'paypal', 'IPN subscription end-of-term for order ' . $order_id );

            // Record subscription ended
            $order->add_order_note( __( 'IPN subscription end-of-term for order.', WC_Subscriptions::$text_domain ) );

            // Ended due to failed payments so cancel the subscription
            if ( time() < strtotime( WC_Subscriptions_Manager::get_subscription_expiration_date( WC_Subscriptions_Manager::get_subscription_key( $order->id ), $order->customer_user ) ) )
                WC_Subscriptions_Manager::cancel_subscriptions_for_order( $order );
            else
                WC_Subscriptions_Manager::expire_subscriptions_for_order( $order );
        }
        break;

    case 'subscr_failed': // Subscription sign up failed

        if ( self::$debug ) 
            self::$log->add( 'paypal', 'IPN subscription sign up failure for order ' . $order_id );

        // Subscription Payment completed
        $order->add_order_note( __( 'IPN subscription sign up failure.', WC_Subscriptions::$text_domain ) );

        WC_Subscriptions_Manager::failed_subscription_sign_ups_for_order( $order );

        break;
}

Step 4: Failed Payments

Subscriptions also provides an API for handling failed payments, which your extension may or may not need to use depending on whether your payment gateway will process failed payments.

There are two functions available:

<?php WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order, $product_id ) ?>

You should pass the order ID or order object for the order used to purchase the subscription (the parent order). The status of this order won’t be changed, instead it will be used to look up the subscription and create a renewal order with the “failed” status.

<?php WC_Subscriptions_Manager::process_subscription_payment_failure( $user_id, $subscription_key ) ?>

The first of these is a convenience wrapper for the second, so you can use either, but not both.

When Subscriptions processes a failed payment, it will put the subscription on-hold until the customer has logged in to manually complete payment for the renewal period. The payment method used for making that payment will also be used for future recurring payments, as long you handle recurring payment method changes, as covered in the next section.

If your gateway does not manage failed payments for you, you must use one of the failed payments API functions.

Step 5: Recurring Payment Method Changes

Subscriptions 1.4 introduced a way for customers to change the payment method used for future payments on their subscription. It also uses this method to update the payment method on a subscription when a recurring payment failed.

To handle recurring payment method changes, your gateway needs to:

1. add 'subscription_payment_method_change' supports flag so that your gateway is presented as a payment option when the customer is changing the payment; and
2. hook to the 'woocommerce_subscription_failing_payment_method_updated_{your-gateway}' action to update the payment method when a customer is making a payment in lieu of an automatic renewal payment that previously failed.

5.1: Supporting Subscriber Payment Method Changes

To support customer initiated payment method changes, your extension will only need to be able to process subscription orders with a $0 initial total. Subscriptions creates a mock checkout using the original order details and overriding the total to be $0. If your payment gateway extension correctly handles a $0 initial total, as it will need to do to process free trial periods correctly, then it shouldn’t need any additional code to handle payment method changes.

The only time it will need additional code, is if the billing schedule is managed by the Payment Gateway, not by Subscriptions. In this case, you may also need to set the correct first payment date (in a similar fashion to the way you set a free trial on a standard subscription sign-up).

In these cases, you can check if the $order_id parameter passed to your gateway’s process_payment() method is for a subscription using wcs_is_subscription( $order_id ). When your gateway’s process_payment() is called with the ID of a subscription, it means the request is to change the payment method on the subscription.

5.2: Updating the Payment Method After a Failure

If a subscriber’s automatic payment fails, her subscription will be put on-hold until she logs in to complete the payment.

As of Subscriptions 1.4, the recurring payment method use for future payments will be updated to the payment method used to complete this payment. As a result, you will need to update any meta data on the original subscription that is required by your payment gateway to handle future automatic payments. You must update the meta data on the 'woocommerce_subscriptions_changed_failing_payment_method_{your-gateway}' hook, if you do not, all future automatic payment will continue to fail.

You do not need to update the the payment method or anything else on the original order, Subscriptions will handle that, simply make sure the original order has whatever meta data is required to correctly handle future payments and manage the subscription.

Below is some example code similar to that used in Stripe and Authorize.net CIM to fulfill this requirement. It updates the customer token on the original subscription order by accessing the customer token from the new renewal order.

/**
 * Update the customer token IDs for a subscription after a customer used the gateway to successfully complete the payment
 * for an automatic renewal payment which had previously failed.
 *
 * @param WC_Order $original_order The original order in which the subscription was purchased.
 * @param WC_Order $renewal_order The order which recorded the successful payment (to make up for the failed automatic payment).
 * @return void
 */
function yg_update_failing_payment_method( $original_order, $new_renewal_order ) {
    update_post_meta( $original_order->id, '_your_gateway_customer_token_id', get_post_meta( $new_renewal_order->id, '_your_gateway_customer_token_id', true ) );
}
add_action( 'woocommerce_subscriptions_changed_failing_payment_method_your_gateway', 'yg_failing_payment_method', 10, 2 );

For payment gateway changes to work, your extension will also need to be able to process subscription orders with a $0 initial total

Step 6: Testing Renewal Payments

Once you have everything set-up and working, you may want to test recurring payments.

To test recurring payments, following the instructions in the guide to triggering subscription renewals.

You can also use this method to test payment failures. To do so, delete or modify the meta data that is used to process the payment. For example, you could change the '_stripe_customer_id' for Stripe or '_wc_authorize_net_cim_payment_profile_id' for Authorize.net CIM as stored in the post meta table against the original subscription order. When the payment is processed, it will fail as the customer token is invalid, and therefore, trigger the failed renewal process.

FAQs

How can I debug issues with renewal orders?

If a renewal payment is being processed correctly at the payment gateway but the renewal order’s status is not being set to processing or completed, then it is likely a PHP fatal error is occurring during the renewal process. This error may be caused by custom code, plugin conflicts or other server related issues.

To diagnose these issues, it is essential to review the PHP error logs for your website. Unfortunately, there is no standard location for the PHP error log, and it can be set to be stored in a different location depending on your host. To find the PHP error log, you can:

1. Create a file name phpinfo.php in the root of your WordPress’s directory
2. Open the phpinfo.php file in a text editor
3. Insert the following code into the file: <?php phpinfo(); ?>
4. Open the file on your site, for example, if your site’s URL is example.com, you can open the file by visiting http://example.com/phpinfo.php
5. Search the page for the error_log value. The file path listed here is the absolute file path of the PHP error log – visit that address on your server and you should find the PHP error log. If the value is empty, then you need to set a value to log errors on your site.

Once you have a copy of your PHP error log, you can look for entries beginning PHP Fatal error around the time of renewal. The error listed here will indicate the cause of the issue.

The post Subscriptions Payment Gateway Integration Guide first appeared on CODIBU.

The following guide is written for developers who want to add fees to the WooCommerce cart and would like to learn about how these fees interact with WooCommerce Subscriptions.

The guide explains how fees added to the cart act by default, and how they can be customized to be applied only to the initial order or recurring orders.

Understanding Cart Fees

Unlike cart items, cart fees are non-persistent, this means third-party plugins which add fees need to be constantly hooked into the cart calculations, adding their fees each time the cart totals are calculated.

To do that WooCommerce provides the woocommerce_cart_calculate_fees hook, which third parties can use to add their fees.

For example, to add a $10 engraving fee to the cart, you could use the following code snippet:

add_filter( 'woocommerce_cart_calculate_fees', 'add_engraving_fees', 10, 1 );

function add_engraving_fees( $cart ) {
     $cart->add_fee( 'Engraving', '10' );
}

This fee will appear like this in the cart totals section of the cart page:

WooCommerce Subscriptions’ recurring carts use the same cart calculations and so the code snippet above also applies the fees to any recurring cart. That is to say, by default, any cart fees added using the woocommerce_cart_calculate_fees hook will be applied both to both the initial order, and any subscriptions created for that transaction. Those fees are then also applied to subsequent transactions.

So for example, using the same code snippet above, customers purchasing subscriptions would see the following cart totals:

Recurring Only Fees

As mentioned above, by default, fees applied to the cart are applied to be the initial and recurring carts.

In some cases, you may require the fee to only apply to the on-going recurring payment for any subscriptions. To achieve this, you need to tweak the code snippet from above and add a condition to check whether the cart being passed into your callback is a recurring cart, or the standard WooCommerce cart.

Recurring carts have a $recurring_cart_key property we can use to determine if the cart is a recurring cart.

For example:

add_filter( 'woocommerce_cart_calculate_fees', 'add_recurring_postage_fees', 10, 1 );

function add_recurring_postage_fees( $cart ) {
    if ( ! empty( $cart->recurring_cart_key ) ) {
        $cart->add_fee( 'Postage', 5 );
    }
}

Initial Order Only Fees

For situations where fees should only be charged on the initial order when the customer signs up, there are two options to add a fee only to the initial order:

Option 1: Invert check for recurring cart

add_filter( 'woocommerce_cart_calculate_fees', 'add_administration_fees', 10, 1 );

function add_administration_fees( $cart ) {
    if ( empty( $cart->recurring_cart_key ) ) {
        $cart->add_fee( 'Processing Fee', 2.5 );
    }
}

In this example, we’ve reversed the logic from the previous code example. This code now only applies fees to the initial purchase cart.

Option 2: Apply fee to global cart

add_filter( 'woocommerce_cart_calculate_fees', 'add_administration_fees', 10 );

function add_administration_fees() {
    WC()->cart->add_fee( 'Processing Fee', 2.5 );
}

In this example, we’re applying the fee to the global WooCommerce cart object. This is the default cart object and so only applies fees to the initial purchase.

The Recurring Fee Filter

WooCommerce Subscriptions 2.2.16 introduced the woocommerce_subscriptions_is_recurring_fee filter. This filter allows developers who have applied fees to the initial cart to also apply the fees to the recurring cart.

For example, if the cart fees have been applied using WC()->cart->add_fee( 'Fee', '10' );, you could use this filter to also apply it to all recurring carts.

By default, the return value of this filter is set to false, so that all fees applied using WC()->cart are non-recurring fees by default.

// All fees are recurring
add_filter( 'woocommerce_subscriptions_is_recurring_fee', '__return_true' );

add_filter( 'woocommerce_cart_calculate_fees', 'add_fees', 10 );

function add_fees() {
    WC()->cart->add_fee( 'Fee', '10' );
}

If only certain fees are recurring or you would like to apply more complex conditions, you can use the $fee and $cart filter arguments.
For example:

add_filter( 'woocommerce_cart_calculate_fees', 'add_fees', 10 );

function add_fees() {
    WC()->cart->add_fee( 'Personal Engraving', 10 );
    WC()->cart->add_fee( 'Postage', 5 );
}

add_filter( 'woocommerce_subscriptions_is_recurring_fee', 'apply_recurring_fees', 10, 3 );

function apply_recurring_fees( $is_recurring, $fee, $cart ) {

    // Personal engraving fees should be charged on a recurring basis
    if ( 'personal-engraving' === $fee->id ) {
        $is_recurring = true;
    // Subscriptions with a recurring total less than $30 are required to pay on-going postage charges
    } elseif ( 'postage' === $fee->id && 30 > $cart->get_subtotal() ) {
        $is_recurring = true;
    }

    return $is_recurring;
}

The post Developer Guide to Cart and Recurring Cart Fees first appeared on CODIBU.

WooCommerce Subscriptions is a premium plugin, and version 2.1 introduced a new system to automatically retry a recurring payment that previously failed.

This guide provides a technical overview of the Failed Recurring Payment Retry system and is intended for developers looking to customize or otherwise interact with the retry system.

We recommend reading the Store Owner Guide to the Failed Payment Retry System for a non-technical introduction to the retry system.

Retry System Components

The retry system is made up of a number of different components, each of which implements a distinct aspect of the retry system. These components are:

• WCS_Retry_Manager: Manages the entire retry system, from loading all components to hooking into the normal failed payment flow, checking retry rules and applying a rule to retry a failed renewal payment when required.
• WCS_Retry_Rules: Sets up the default store-wide rules for retrying failed automatic renewal payments and provides methods for working with rules, like get_rule().
• WCS_Retry_Rule: Represents instance of a retry rule and provides methods for retrieving and checking a rule’s properties. Used by WCS_Retry_Rules->get_rule() and WCS_Retry->get_rule().
• WCS_Retry: Represents instance of a retry and provides methods for retrieving and checking properties on a retry, like get_order_id() and get_rule().
• WCS_Retry_Store: Provides an extensible interface to store a retry in the database.
• WCS_Retry_Post_Store: Implements WCS_Retry_Store to store retry details in the WordPress posts table as a custom post type.
• WCS_Retry_Database_Store: Implements WCS_Retry_Store to store retry details in the wcs_payment_retries custom table.
• WCS_Retry_Hybrid_Store: The hybrid store acts as a bridge between the two default stores and migrates retries from the post store to the database store when a retry is retrieved from the post store. This store also extends WCS_Retry_Store.
• WCS_Retry_Background_Migrator: This class extends the WCS_Background_Upgrader class and handles the migration of retries using WCS_Retry_Migrator in the background via an Action Scheduler action.
• WCS_Retry_Migrator: The retry migrator contains the logic behind the migration from the post store to the database store.
• WCS_Retry_Stores: Managers the two default store interfaces and contains functions to access them. Use WCS_Retry_Stores::get_post_store() or WCS_Retry_Stores::get_database_store() to get the stores.
• WCS_Retry_Email: Manages emails sent as part of the retry process by registering the custom retry email classes and sending emails on relevant hooks.
• WCS_Email_Payment_Retry: Controls the email template sent to store owners when an attempt to automatically process a subscription renewal payment has failed and a retry rule has been applied to retry payment in the future.
• WCS_Email_Customer_Payment_Retry: Controls the email template sent to the customer/subscriber when an attempt to automatically process a recurring payment has failed and a retry rule has been applied to retry payment in the future.
• WCS_Retry_Admin: Sets up the administration UI elements, including the Automatic Failed Payment Retries meta box and the setting to Enable the Retry System.
• WCS_Retry_Table_Maker: Extends WCS_Table_Maker, and defines the version and table definition for the retries custom database.

Retry Process Flow

The Store Owner Guide provides a non-technical overview of the Retry Process. This section provides a technical guide, including details of hooks involved in the process.

How general retry process proceeds:

1. The 'woocommerce_subscription_renewal_payment_failed' action is triggered in WC_Subscription->payment_failed() after a renewal payment fails.
2. The WCS_Renewal_Retry_Manager::maybe_apply_retry_rule() is called, as it’s attached to 'woocommerce_subscription_renewal_payment_failed'.
3. WCS_Renewal_Retry_Manager::maybe_apply_retry_rule() checks:
   • the subscription is manual: $subscription->is_manual().
   • automatic retry is possible with the payment method on the subscription: $subscription->payment_method_supports( 'gateway_scheduled_payments' ).
   • the last order is a renewal: wcs_order_contains_renewal( $last_order ).
   • there is a retry rule for this stage of the retry process and for this specific order: WCS_Renewal_Retry_Manager::rules()->has_rule( WCS_Renewal_Retry_Manager::store()->get_retry_count_for_order( $renewal_order->id ), $renewal_order->id ).
4. If all these conditions pass:
   • A new pending retry is saved to correspond to the rule: WCS_Renewal_Retry_Manager::store()->save( $retry ).
   • Status of the renewal order is updated according to the rule: $order->update_status( $new_status ).
   • Status of the subscription is updated according to the rule: $subscription->update_status( $new_status ).
   • Interval time defined by the retry rule is then used to set the retry date/time on the subscription: $subscription->update_dates( array( 'payment_retry' => gmdate( 'Y-m-d H:i:s', gmdate( 'U' ) + $retry_rule->get_retry_interval( $retry_count ) ) ) ).
5. When the scheduled time for the retry event arrives, the 'woocommerce_scheduled_subscription_payment_retry' action will be triggered passing callbacks the ID of the renewal order to which the retry relates.
6. The WCS_Renewal_Retry_Manager::maybe_retry_payment() is called, as it is hooked to 'woocommerce_scheduled_subscription_payment_retry'.
7. WCS_Renewal_Retry_Manager::maybe_retry_payment() checks:
   • Retry still has pending status
   • Last order still needs payment: $last_order->needs_payment()
8. If these checks fail, the status of the retry is transitioned to 'cancelled'.
9. If they pass, WCS_Renewal_Retry_Manager::maybe_retry_payment() will transition the retry to the 'processing' status and then check:
   • Last order still has the status defined by the retry rule applied to it (if a status was defined): $last_order->has_status( $last_retry->get_rule()->get_status_to_apply( 'order' ) ).
   • Subscription still has the status defined by the retry rule applied to it (if a status was defined): $subscription->has_status( $last_retry->get_rule()->get_status_to_apply( 'subscription' ) ).
10. If these additional checks fail, the status of the retry will be transitioned to 'cancelled'
11. If they pass, WCS_Renewal_Retry_Manager::maybe_retry_payment() will then:
    • Update the subscription status to on-hold in preparation for payment (Subscriptions uses this status immediately before payment regardless of status defined by the retry rule to avoid compatibility issues with payment gateways that expect the subscription to have on-hold status, as it would for normal recurring payments): $subscription->update_status( 'on-hold' ).
    • Tell the payment gateway on the subscription to process payment for the last order: WC_Subscriptions_Payment_Gateways::gateway_scheduled_subscription_payment( $subscription ).
12. WCS_Renewal_Retry_Manager::maybe_retry_payment() will then check the order again and if it does not need payment, the status of retry is transitioned to 'complete' status as the last payment must have been processed correctly.
13. If the last order still needs payment, the retry is transitioned to 'failed' status as the last payment did not process correctly.
14. If payment failed, WC_Subscription->payment_failed() will trigger 'woocommerce_subscription_renewal_payment_failed' again and the process repeats from step 1.

Customizing the Retry Process

The retry process is based on a set of retry rules, as explained in the Store Owner Guide to the Failed Payment Retry System.

These rules can be customized by changing both the default rule applied to all failed payments in the store and/or one specific rule applied to a given order.

Rule Data Structure

Retry rule data can take two forms:

• A raw retry rule is an array. This is the form used to store the default rule set in the protected WCS_Retry_Rules->default_retry_rules property and to store the rule applied for a specific retry in the database.
• An instance of WCS_Retry_Rule (or child class of WCS_Retry_Rule). This is the form used to work with a specific rule.

Raw Rule Data Structure

The raw rule format is an array with the following values:

• retry_after_interval: Amount of time, in seconds, between when the rule is applied and when to reattempt payment. Note: This interval accumulates between rules. For example, consider a store with two rules, the first with an interval of 24 hours and the second with an interval of 48 hours. If the 1st retry attempt fails, the 2nd retry attempt will be run 48 hours after it fails, not 48 hours after the first payment failed. This is 72 hours after first payment failure.
• email_template_customer: Class name of the email template to send the customer when the retry rule is applied (i.e. the payment fails). If empty, no email is sent.
• email_template_admin: Class name of the email template to send the store owner when the retry rule is applied (i.e. the payment fails). If empty, no email is sent.
• status_to_apply_to_order: Status to apply to the renewal order between when payment fails and when it is attempted again. This is not the status applied after the payment attempt for this retry rule fails. It is the status applied at the time the retry rule is applied, which happens when the previous payment attempt failed. This can be either the full, internal status name, e.g. wc-pending or shorthand status name, e.g. pending.
• status_to_apply_to_subscription: Status to apply to the subscription between when payment fails and when it is attempted again. This is not the status applied after the payment attempt for this retry rule fails. It is the status applied at the time the retry rule is applied, which happens when the previous payment attempt failed. This can be either the full, internal status name, e.g. wc-on-hold or shorthand status name, e.g. on-hold.

This snippet provides an example of rule in the raw, array data structure.

array(
    'retry_after_interval'            => DAY_IN_SECONDS,
    'email_template_customer'         => 'WCS_Email_Customer_Payment_Retry',
    'email_template_admin'            => 'WCS_Email_Payment_Retry',
    'status_to_apply_to_order'        => 'pending',
    'status_to_apply_to_subscription' => 'on-hold',
),

Rule Class Data Structure

The WCS_Retry_Rule class is used by default to instantiate retry rule data into the object used in WCS_Retry_Manager and elsewhere.

The class used to instantiate rule data can also be customized with the 'wcs_retry_rule_class' filter. In most cases, this is unnecessary. It is only necessary to achieve behavior not customizable via custom rule filters detailed below.

This snippet provides an example of using a custom rule class.

function eg_my_custom_retry_rule_class( $default_retry_class ) {
    return 'EG_Retry_Rule';
}
add_filter( 'wcs_retry_rule_class', 'eg_my_custom_retry_rule_class' );

Custom Storewide Rules

The retry system uses a default set of rules for managing all failed payments in the store. These rules are defined in WCS_Retry_Rules::__construct() and accessed via WCS_Retry_Rules::get_rule().

Customizing the default retry rules makes it possible to apply a new set of rules that are better suited to unique requirements for your store. For example, if a store only sells annual subscriptions, you may wish to use retry rules that continue retrying for up to 30 days after the initial payment failed, rather than the much shorter default.

The 'wcs_default_retry_rules' filter makes it possible to customize the default rules. This filter passes callbacks an array of rules in the raw array rule data structure, and expects to receive the same from callbacks.

Note: To apply code to the 'wcs_default_retry_rules' filter, your add_filter() call will need to occur before WCS_Retry_Rules is first instantiated, which is attached to the 'woocommerce_subscription_renewal_payment_failed' and 'woocommerce_scheduled_subscription_payment_retry' hooks.

Example Custom Default Rules

This snippet provides a complete set of custom rules that will:

• Retry a payment 5 times over the course of a month, instead of the default 7 days
• Implement more advanced dunning than the default rules, by sending three different emails to the customer
• Only notify the store owner of the failed payment via email on the first and last retry attempt
• Leave the subscription active for the first 7 days to provide a grace period before blocking access to virtual content linked to the subscription

function eg_my_custom_retry_rules( $default_retry_rules_array ) {
    return array(
            array(
                'retry_after_interval'            => 3 * DAY_IN_SECONDS,
                'email_template_customer'         => '',
                'email_template_admin'            => 'WCS_Email_Payment_Retry',
                'status_to_apply_to_order'        => 'pending',
                'status_to_apply_to_subscription' => 'active',
            ),
            array(
                'retry_after_interval'            => 4 * DAY_IN_SECONDS,
                'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_First_Nag', // custom email
                'email_template_admin'            => '',
                'status_to_apply_to_order'        => 'pending',
                'status_to_apply_to_subscription' => 'active',
            ),
            array(
                'retry_after_interval'            => WEEK_IN_SECONDS,
                'email_template_customer'         => '', // avoid spamming the customer by not sending them an email this time either
                'email_template_admin'            => '',
                'status_to_apply_to_order'        => 'pending',
                'status_to_apply_to_subscription' => 'on-hold',
            ),
            array(
                'retry_after_interval'            => WEEK_IN_SECONDS,
                'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_Second_Nag', // custom email
                'email_template_admin'            => '',
                'status_to_apply_to_order'        => 'pending',
                'status_to_apply_to_subscription' => 'on-hold',
            ),
            array(
                'retry_after_interval'            => WEEK_IN_SECONDS,
                'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_Final_Nag', // custom email
                'email_template_admin'            => 'WCS_Email_Payment_Retry',
                'status_to_apply_to_order'        => 'pending',
                'status_to_apply_to_subscription' => 'on-hold',
            ),
        );
}
add_filter( 'wcs_default_retry_rules', 'eg_my_custom_retry_rules' );

Custom Individual Rule

You may wish to apply different retry rules for different products, billing schedules, payment amounts or other conditions. To do this, you can customize a specific retry rule based on the order ID and its position in the retry queue.

An individual rule can be customized in two ways, depending on the data structure of the rule.

To customize the raw rule in array format, use the 'wcs_get_retry_rule_raw' filter. To customize the instantiated rule object, use the 'wcs_get_retry_rule' filter.

Callbacks on both of these filters receive 3 parameters:

1. $rule: this will be:
   • an array representing the rule with the array keys described above for 'wcs_get_retry_rule_raw'.
   • an instance of WCS_Retry_Rule for 'wcs_get_retry_rule'.
   • null if there is no rule for this $retry_number and $order_id.
2. $retry_number: the position in the retry queue, starting at 0. For example, after the first payment failure, there have been no retries, so the $retry_number would be 0. If the retry fails after applying this first rule, to get the rule for the 2nd retry, the $retry_number would then be 1.
3. $order_id: the ID of the order for which this rule relates.

Example Custom Individual Raw Rule

This snippet changes the email template sent to customers for a product with ID 30.

function eg_my_custom_retry_rule( $rule_raw, $retry_number, $order_id ) {

    $order       = wc_get_order( $order_id );
    $has_product = false;

    foreach ( $order->get_items() as $line_item ) {
        if ( $line_item['product_id'] == 30 ) {
            $has_product = true;
            break;
        }
    }

    if ( $has_product && ! empty( $rule_raw['email_template_customer'] ) ) {
        $rule_raw['email_template_customer'] = 'EG_Email_Customer_Payment_Retry_Product_Thirty';
    }

    return $rule_raw;
}
add_filter( 'wcs_get_retry_rule_raw', 'eg_my_custom_retry_rule' );

Example Custom Individual Rule Object

This snippet uses a custom retry rule class and interval for annual subscriptions.

function eg_my_custom_retry_rule( $rule, $retry_number, $order_id ) {

    $subscription = wcs_get_subscriptions_for_order( $order, array( 'order_type' => 'renewal' ) );

    if ( ! empty( $subscription ) && 'year' === $subscription->billing_period ) {

        $existing_rule_raw = $rule->get_raw_data();

        if ( ! empty( $existing_rule_raw['retry_after_interval'] ) ) {
            $existing_rule_raw['retry_after_interval'] = WEEK_IN_SECONDS;
            $rule = new EG_Retry_Rule( $rule->get_rule_raw() );
        }
    }

    return $rule;
}
add_filter( 'wcs_get_retry_rule', 'eg_my_custom_retry_rule' );

Testing the Retry System

After creating custom retry rules, or to check whether your gateway is compatible with the retry system, you can test the retry system with the following process.

Step 1: Enable the Retry System

Before testing, ensure that you have enabled the Retry System in your store.

Step 2: Trigger a Failed Recurring Payment

Depending on your gateway, the way to trigger a recurring payment failure will differ. For Stripe and other payment gateways that support admin payment method changes you can:

1. Purchase a subscription using a payment method which supports payment date changes
2. Go to: WooCommerce > Edit Subscription for that subscription
3. Click the pencil icon next to Billing Details
4. Enter dummy payment token meta data so that the payment will fail
5. Click Save Subscription
6. After the page has reloaded, click the Actions select box in the Subscription Actions metabox
7. Click Process Renewal
8. Click Save Subscription

This creates a renewal order, records the failed payment on that renewal and applies the first retry rule to that order.

Step 3: Monitor Retries

At this stage, you can view the details of the Pending retry via the interfaces detailed in the Store Manager guide to Monitoring Retries.

If your retry rule worked, you should now be able to see:

• A Renewal Payment Retry date on the WooCommerce > Edit Subscription administration screen
• A Pending retry in the Automatic Failed Payment Retries metabox

Step 4: Trigger the Retry (Optional)

If you do not want to wait until the retry is triggered automatically, you can trigger the retry immediately.

To trigger a scheduled payment retry hook immediately:

1. Make sure your store is running in debug mode by setting the WP_DEBUG constant
2. Visit your WordPress administration dashboard
3. Go to: Tools > Scheduled Actions
4. In the search box, enter the ID of your test order
5. Find the row with the hook 'scheduled_subscription_payment_retry' and the status pending
6. Hover over the row and click Run

This immediately triggers the 'scheduled_subscription_payment_retry' hook.

Retry Migration to Custom Table

When the retry system was introduced in 2.1, retries were a custom post type and were stored in the WordPress posts and postmeta tables. To improve the performance of the retry system, in version 2.4 we introduced a custom table to store the retry data. With the introduction of this custom table, we needed to migrate the existing data.

Retries are migrated to the custom table in 2 ways:

1. On the fly: while retries still exist in the posts table, the WCS_Retry_Hybrid_Store is used to act as a bridge between the two data stores. When a retry object is requested (e.g. via WCS_Retry_Manager::store()->get_retry( $retry_id )), the hybrid store will first check if the retry exists in the post table and if it does, it will migrate the retry data to the new custom table before returning the retry object.
2. In the background: when the store upgrades to 2.4, or any version after 2.4, a migration action will be scheduled via the Action Scheduler library. When this action is triggered, the WCS_Retry_Background_Migrator class will migrate retries in batches, rescheduling itself every 60 seconds (by default) until all retries have been migrated. WCS_Retry_Background_Migrator is initialized by and stored on WCS_Retry_Manager as protected variable.

How do I track the progress of the retry data migration?

The status of the retry data migration is displayed in the System Status.

1. Go to WooCommerce > Status.
2. Scroll down to Retries Migration Status.

How can I tell how many retries still need to be migrated?

To see how many retries you still have stored in the posts table:

1. Go to WooCommerce > Status and scroll down to the Post Type Counts section.
2. The number next to payment_retry is the number of retries which haven’t been mirgrated.

If there isn’t any payment_retry row displayed in this table, there aren’t any retries still stored in the posts table.

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

This article provides developer documentation for adding support to a payment gateway extension for Subscription v2.0’s new Change Payment Method section of the Edit Subscription administration screen.

If you are a developer of a payment gateway and have not yet provided support for processing subscriptions, please read the Subscriptions Payment Gateway Integration Guide.

Background

A new feature added in Subscriptions v2.0 provides a way for payment gateways to allow store managers to add or edit a subscription’s payment method and meta data on the new Edit Subscription administration screen.

Adding support for this feature can be achieved with any payment gateway that uses customer or credit card tokens with the following steps:

1. Add the support flag to your gateway to declare support for store managers to change the payment methods
2. Allow store managers to change the payment meta data
3. Validate the new meta data before saving the subscription.

Step 1. Declare Support for Changing Payment Methods

By default, Subscriptions will not allow store managers to change or modify the payment gateway on the Edit Subscription screen to anything other than the built-in Manual Renewals gateway.

To add the support for this feature, you will need to declare support by adding 'subscription_payment_method_change_admin' to your gateway’s $this->supports property.

For example, if Stripe wanted to allow administrators to change the payment method, they could achieve this by adding the 'subscription_payment_method_change_admin' to their WC_Payment_Gateway->supports array as follows:

$this->supports = array(
    // Other support flags here
    'subscription_payment_method_change_admin',
    // Other support flags here
);

Once your gateway declares support, it will be included as an option on the Edit Subscription page.

Step 2: Declare your Payment Gateway’s Meta Data

To allow store managers to correctly configure automatic payments with your payment gateway via the Edit Subscription screen, you also need to tell Subscriptions about the meta data required by your payment gateway in order to process automatic payments. This is done using the filter: 'woocommerce_subscription_payment_meta'.

Callbacks on this hook are passed an array of meta data for all payment gateways in the store and an instance of the subscription (a WC_Subscription) to which the meta data relates.

To use this filter correctly, you need to insert information about your payment details using your payment gateway’s ID as the key on the array, i.e. payment_meta[ YOUR_GATEWAY_ID ]. You should also populate the meta data with the current or default value for the given subscription, which is passed to your callback as the 2nd parameter.

The full structure needs to meet the following format:

$payment_meta[ YOUR_GATEWAY_ID ]  = array (
    'table_name' => array (
        'meta_key_1' => array (
            'value' => get_post_meta( $subscription->id, ..., true ),
            'label' => 'Front-end Label to display',
        ),
        'meta_key_2' => array (
            'value' => get_user_meta( $subscription->customer_user, ..., true ),
            'label' => 'Front-end Label to display',
        )
    ),
);

Subscriptions uses this information in two ways:

• to display the appropriate fields on the Edit Subscription screen, which is why a 'label' field is required; and
• to save the meta data in the database when the Edit Subscription screen is saved, which is why the meta key and table name fields are required.

The 'table_name' string tells Subscriptions where to store and retrieve the meta data. If the value is either 'post_meta', 'user_meta' or 'options', subscriptions will automatically save the new data to those respective tables with the site’s database prefix (i.e. wpdb->prefix). If the default table names are not suitable for storing your data, please read the FAQ section for details of alternatives.

Specifically:

• Any data found in payment_meta[ YOUR_GATEWAY_ID ]['post_meta'] will be stored in the post meta table using update_post_meta( $subscription, 'meta_key', $new_data);
• Data found in payment_meta[ YOUR_GATEWAY_ID ]['user_meta'] will be saved as update_user_meta( $subscription->customer_user, 'meta_key', $new_data );;
• The data listed under payment_meta[ YOUR_GATEWAY_ID ]['options'] will be saved to options table using update_option( 'meta_key', $new_data ).

Example: Stripe

Here’s an example of how the Stripe payment gateway uses this filter to allow administrators to change the '_stripe_customer_id' meta data found in the post meta table and similarly the '_stripe_card_id' meta data.

class WC_Gateway_Stripe_Addons extends WC_Gateway_Stripe {

    ...

    /**
     * Include the payment meta data required to process automatic recurring payments so that store managers can
     * manually set up automatic recurring payments for a customer via the Edit Subscriptions screen in 2.0+.
     *
     * @since 2.5
     * @param array $payment_meta associative array of meta data required for automatic payments
     * @param WC_Subscription $subscription An instance of a subscription object
     * @return array
     */
    public function add_subscription_payment_meta( $payment_meta, $subscription ) {

        $payment_meta[ $this->id ] = array(
            'post_meta' => array(
                '_stripe_customer_id' => array(
                    'value' => get_post_meta( $subscription->id, '_stripe_customer_id', true ),
                    'label' => 'Stripe Customer ID',
                ),
                '_stripe_card_id' => array(
                    'value' => get_post_meta( $subscription->id, '_stripe_card_id', true ),
                    'label' => 'Stripe Card ID',
                ),
            ),
        );

        return $payment_meta;
    }

    ...
}

Step 3: Validate Meta Data

To ensure store managers are inputting correct data, an optional but highly recommended feature you can implement is validation of the data before it is saved to the subscription.

The 'woocommerce_subscription_validate_payment_meta' filter is available for this purpose. This filter passes payment_method_id and payment_meta array parameters to callbacks. The payment_meta contains all the user’s inputted data in the same format as described in Step 2. Attach a validation function to this filter to validate meta data entered by the store manager.

Any exceptions thrown in your validation function will be caught and the exception message will be displayed on the Edit Subscription in an administration notices section (see below). If an exception is caught, all new modifications before saving the subscription will be ignored.

function my_validation_function( $payment_method_id, $payment_meta ) {

    if ( 'YOUR_GATEWAY_ID' === $payment_method_id ) {
        if ( 'example_throw' == $payment_meta['YOUR_GATEWAY_ID']['post_meta']['example_meta_key'] ) {
            throw new Exception( 'Error to appear on Edit Subscription in the case of an invalid input' );
        }   
    }
}
add_action( 'woocommerce_subscription_validate_payment_meta', 'my_validation_function', 10, 2 );

Example: Stripe

The following codes demonstrate the validation function used by the Stripe Payment Gateway to validate its data.

class WC_Gateway_Stripe_Addons extends WC_Gateway_Stripe {

    ...

    /**
     * Validate the payment meta data required to process automatic recurring payments so that store managers can
     * manually set up automatic recurring payments for a customer via the Edit Subscriptions screen in 2.0+.
     *
     * @since 2.5
     * @param string $payment_method_id The ID of the payment method to validate
     * @param array $payment_meta associative array of meta data required for automatic payments
     * @return array
     */
    public function validate_subscription_payment_meta( $payment_method_id, $payment_meta ) {

        if ( $this->id === $payment_method_id ) {

            if ( ! isset( $payment_meta['post_meta']['_stripe_customer_id']['value'] ) || empty( $payment_meta['post_meta']['_stripe_customer_id']['value'] ) ) {
                throw new Exception( 'A "_stripe_customer_id" value is required.' );
            } elseif ( 0 !== strpos( $payment_meta['post_meta']['_stripe_customer_id']['value'], 'cus_' ) ) {
                throw new Exception( 'Invalid customer ID. A valid "_stripe_customer_id" must begin with "cus_".' );
            }

            if ( ! isset( $payment_meta['post_meta']['_stripe_card_id']['value'] ) || empty( $payment_meta['post_meta']['_stripe_card_id']['value'] ) ) {
                throw new Exception( 'A "_stripe_card_id" value is required.' );
            } elseif ( 0 !== strpos( $payment_meta['post_meta']['_stripe_card_id']['value'], 'card_' ) ) {
                throw new Exception( 'Invalid card ID. A valid "_stripe_card_id" must begin with "card_".' );
            }
        }
    }

    ...

}

Full Example: Simplify Commerce

For a full example, see the code required to add support to Simplify Commerce in WooCommerce core in this commit. This was submitted as part of the Simplify Commerce Subscriptions v2.0 compatibility pull request.

Testing

Once you have completed the steps above, your gateway should:

1. be presented as a payment method option on the Edit Subscription screen;
2. display and save meta data required for processing automatic payments with your gateway; and
3. check that the meta data entered by the store manager is valid.

To ensure that automatic recurring payments work with the new meta data:

1. Visit the WooCommerce > Subscriptions screen
2. Click the ID of a subscription to open the Edit Subscription screen
3. Click the pencil icon next to the Billing Details section
4. Verify that all the fields required for processing automatic payment are displayed
5. If they are, enter _invalid_ meta data for each field
6. Save the subscription
7. Ensure that correct admin notices are displayed (i.e. your validation function’s exception messages)
8. Repeat the above 3 steps for each field your gateway requires
9. Enter valid meta data for each field
10. Save the subscription
11. trigger an early renewal payment for the subscription
12. verify that the renewal payment was processed correctly (i.e. the renewal order’s status is processing or complete)
13. verify with your payment gateway that the renewal payment used the new customer or card

FAQ

I haven’t added support but my gateway is still showing as an option on the Edit Subscription screen?

If a subscription is purchased via the normal checkout process, the payment method used during checkout will be shown on the Edit Subscription screen because the meta data required for automatic payment should have been collected during checkout.

If the store manager changes the payment method for the subscription from your payment gateway to another, it will no longer be displayed as an option.

How can I save the payment meta for the subscription using my own custom method?

We have provided an action hook that will allow you to save the payment meta data wherever you like, but to ensure you stop us from saving the data, you will need to make sure the table_name does not equal post_meta, postmeta, user_meta, usermeta or options. Then, you should make sure your plugin catches the 'wcs_save_other_payment_meta' action.

The following code example demonstrates how you would go about either storing data in the comments table or attaching some extra information to a value before it is stored in the post meta table.

function my_gateway_meta( $payment_details, $subscription ) {
    $payment_details[ YOUR_GATEWAY_ID ]  = array (
            'wc_comments' => array (
                '_gateway_comments' => array (
                    'value' => get_comments_meta( ..., ..., true ),
                    'label' => 'Front-end Label to display',
                )
            ),
            'wc_post_meta' => array (
                'meta_key_1' => array (
                    'value' => get_post_meta( $subscription->id, 'meta_key_1', true ),
                    'label' => 'Front-end Label to display',
                )
            ),
    );
    return $payment_details;
}
add_filter( 'woocommerce_subscription_payment_meta', 'my_gateway_meta', 10, 2 );

function save_meta_in_comments( $subscription, $table, $meta_key, $meta_value ) {
    switch( $table ) {
        case 'wc_comments':
            update_comments_meta( ..., $meta_key, $meta_value );
            break;
        case 'wc_post_meta':
            update_post_meta( $subscription->id, $meta_key, $meta_value . '_edited' );
            break;
    }
}
add_action( 'wcs_save_other_payment_meta', 'save_meta_in_comments',

The post Admin Change Payment Method Integration Guide first appeared on CODIBU.