Introduction to Subscriptions Developer Documentation

This documentation is written for WooCommerce developers who want to extend or integrate with the Woo Subscriptions plugin. To follow this documentation, you need an advanced understanding of PHP and WordPress development.

If you intend to support Subscriptions in your payment gateway extension, read this overview and then the Payment Gateway Integration Guide.

If you are looking for a guide to creating and managing subscription products in a WooCommerce store, please refer to the Store Manager Guide instead.

Note: We are unable to provide support for customizations under our Support Policy. If you need to customize a snippet or extend its functionality, we recommend working with a Woo Agency Partner or finding a WooCommerce developer on Codeable.

Much like WordPress & WooCommerce, the Subscriptions extension can be extended through an API (Application Programming Interface) of actions, filters and functions.

In addition to this API, it also provides a number of new classes which can be used to instantiate and work with subscription data, both for subscription products and subscriptions.

Action hooks are available for important subscription events. Examples of subscription events include subscription activation, cancellation, expiration. For the full list of action hooks triggered by Woo Subscriptions, see the Action Reference.

Filters are available for formatting and customizing data within the Subscriptions extension, like the “Sign Up Now” button text. For a full list of the available filters, see the Filter Reference.

A range of functions are available to perform subscription related operations, like activating a subscription, and get subscription related information, like its sign-up fee. The most important of these are documented in the Function Reference.

Subscriptions provides a number of classes for instantiating and working with subscription objects, including:

• WC_Subscription: which extends WC_Order to instantiate a subscription object.
• WC_Product_Subscription: which instantiate simple subscription product objects and extends WC_Product_Simple.
• WC_Product_Variable_Subscription: which instantiates variable subscription product objects and extends WC_Product_Variable.
• WC_Product_Subscription_Variation: which instantiates subscription variation objects and extends WC_Product_Variation.

These are discussed in more detail in the Guide to Subscription Data Structures & Storage.

Subscriptions is built on a number of classes. The core of the classes is the WC_Subscriptions class. This sets up the Subscriptions extension and loads all required files.

The rest of the classes:

• Customize a specific WooCommerce class of a similar name, for example WC_Subscriptions_Cart customizes the WC_Cart object.
• Provide an imperative API for working with subscription data, like WC_Subscriptions_Product, which can be used to access subscription product data.
• Instantiate an instance of an object to work with, for example the WC_Subscription which instantiates a subscription.
• Implement all the logic associated with a unique subscriptions feature, like WC_Subscriptions_Switcher or WC_Subscriptions_Synchroniser

Naming conventions for classes follow the WooCommerce convention. For example, the WC_Subscriptions_Order class is located in the file class-wc-subscriptions-order.php file in the /classes/ folder. The difference to WooCommerce is that many of Subscriptions classes use static methods, as each class is created to operate on an object, like the WC_Cart object, rather than create an instance of an object.

Some classes also exist with the WCS_ prefix while others have the more verbose WC_Subscriptions_ prefix. The later of these are a legacy of Subscriptions version 1.n codebase, which used the unfortunately more verbose naming. New classes are almost always use the more concise WCS_ prefix. That is the only reason for the difference.

Technical guides:

• Guide to Multiple Subscriptions
• Guide to Failed Recurring Payment Retry System
• Payment Gateway Integration Guide
• Admin Change Payment Method Integration Guide
• Guide to Cart and Recurring Cart Fees
• Guide to Scheduled Events with Subscriptions

Technical FAQ answers:

• How to Debug Subscriptions PayPal IPN Issues
• How Does Subscriptions Handle Staging Sites and Migrations?
• How to Deactivate Core Subscription Features, like Changing Payment Methods
• How to Remove an Action Button from View Subscriptions Page
• Stop Subscriptions from Changing User Roles
• How to Change Subscriptions to Manual Payments
• How to Customize the My Subscriptions Page

Reference documents:

• Data Structure & Storage
• Subscription Caches
• Subscription Function Reference
  • Subscription Product Function Reference
  • Subscriptions Management Function Reference
  • Subscriptions Order & Cart Function Reference
• Action Reference
• Filter Reference
• Subscription REST API Docs Version 3
• Subscription REST API Docs Version 1
• Legacy Subscription REST API Docs Version 3

These reference guides should not be considered instructive for specific problems, as tutorials, nor exhaustive as they detail only a small subset of the available public API functions and hooks, of which there are many.