Minimum Periods for WooCommerce Subscriptions holds subscribers to a commitment before they can cancel. You set the number of paid periods required, and the Cancel button stays hidden on the customer’s account page until they get there. You can set that number once for the whole store, per product, or per subscription plan.
Overview
↑ Back to topMinimum Periods for WooCommerce Subscriptions requires a subscriber to pay for a set number of billing periods before the Cancel button appears on their My Account subscription page. The initial order counts as the first paid period, so a value of 2 means the subscription has to renew once before the customer can cancel. You set a store-wide default, and you can override it on an individual product, on an individual variation, or on an individual subscription plan. Optional display settings show the minimum period to customers on the product page, in the cart and checkout, on the account page, and in order emails.
Requirements
↑ Back to topBefore you install, check that your store meets these:
- WordPress 6.5 or higher.
- PHP 7.4 or higher.
- WooCommerce 9.0 or higher.
- WooCommerce Subscriptions, active. Both WooCommerce and WooCommerce Subscriptions are declared as required plugins, so WordPress will not let you activate this extension without them.
Two features have extra requirements:
- Per-plan minimum periods need WooCommerce Subscriptions 9.0 or higher, which is where subscription plans were introduced. On earlier versions everything else works as normal, store-wide and per product.
- The AI assistant abilities need WordPress 6.9 or higher (for the Abilities API) plus a separate plugin that exposes abilities to an assistant.
The extension declares compatibility with High Performance Order Storage (HPOS) and with the cart and checkout blocks, so you do not need to turn either off.
Usage
↑ Back to topEverything is configured in three places: a store-wide section in the Subscriptions settings, a per-product field on the product edit screen, and a per-plan field inside the subscription plan dialog. The store-wide section is where you start, because it also carries the switches that turn everything else on.
Store-wide settings
↑ Back to topGo to WooCommerce > Settings > Subscriptions and scroll to the Cancelling section. You can also get there with the Settings link next to the extension on the Plugins screen.
Enable Cancelling controls whether subscribers can cancel at all. It is on by default. Turn it off and the Cancel button never appears, no matter how many periods have been paid. Turning it off also hides the rest of the settings in this section, removes the Cancelling fields from your product screens, removes the Min. Period column from the Products list, and stops every customer-facing message this extension adds. The Suspend button is not affected by this setting.
Default Minimum Period(s) is the number of paid periods required before a subscriber can cancel, counting the initial order as the first. The default is 1, which means the customer can cancel straight away. Set it to 2 to require one renewal, 3 to require two, and so on. This value applies to every subscription product that does not set its own, and to every subscription plan that follows the product or the store.
The remaining settings are display toggles. All of them are off by default, and none of them changes when a customer can cancel. They only decide where the number is shown.
Show Paid Periods adds a row to the subscription details on My Account listing how many periods the customer has paid, per product. The row only appears for products that actually have a minimum period above zero.
Show in Product Pages shows the minimum period on the single product page. For a subscription product it appears above the Add to cart button. For a product sold on subscription plans it appears next to each plan option instead, so the customer sees the commitment attached to the plan they are choosing.
Show in Cart/Checkout shows the minimum period as line item data in the cart and at checkout. For a product sold on plans, the value shown is the one for the plan the customer selected. A one-time purchase shows nothing, because there is no subscription to cancel.
Show in Account Page adds a row to the subscription details on My Account showing the minimum period configured for that subscription, per product.
Show as Subscription Meta shows the minimum period as order line item meta. That covers order confirmation emails, the order received page after checkout, and order details on the account page.
Link Suspensions applies the same rule to the Suspend button that governs the Cancel button. Leave it off and customers can suspend whenever WooCommerce Subscriptions normally allows. Turn it on and the Suspend button stays hidden until the minimum period is met.
Per-product settings
↑ Back to topOpen a product and look on the General tab of the Product data panel for the Cancelling field. It appears for simple, variable, subscription, and variable subscription products, as long as Enable Cancelling is on store-wide.
Cancelling has two options. Use storewide settings means this product follows the store-wide Default Minimum Period(s). Override storewide settings means this product sets its own number.
Minimum Period(s) only appears once you choose Override storewide settings. Enter the number of paid periods required for this product, counting the initial order as the first. Zero means the customer can cancel immediately, which is a useful way to exempt one product from a store-wide commitment.
If the product uses its own custom subscription plans, a note appears under these fields reminding you that each plan can set its own minimum period, and that plans set to follow the product use the value here.
Per-variation settings
↑ Back to topFor a variable subscription product, each variation has its own Cancelling and Minimum Period(s) fields under the variation’s pricing options. They work exactly like the product-level ones.
A variation that does not set its own value falls back to the parent product, and then to the store-wide default.
Per-plan settings
↑ Back to topIf your store runs WooCommerce Subscriptions 9.0 or higher, you can set a minimum period on an individual subscription plan. Use the same dialog you use to add or edit the plan: on the product’s Subscriptions tab for a product’s own plans, or under WooCommerce > Settings > Subscriptions for store-wide plans.
Minimum period has two options. Use product / storewide setting means the plan takes the product’s value, and then the store-wide default. Set for this plan reveals a number field where you enter the paid periods required for this plan alone.
The plans table gains a read-only Min. period column. It shows a number for plans that set their own value, and a dash for plans that follow the product or the store.
Which value applies
↑ Back to topWhen several levels are set, the most specific one wins:
- The subscription plan’s own value, if the plan is set to override.
- Otherwise the product’s own value, if the product is set to override. A variation with nothing of its own uses its parent’s.
- Otherwise the store-wide Default Minimum Period(s).
Nothing is blended. Whichever level supplies the value supplies it in full.
Two rules apply on top of that. If a subscription contains more than one product, the largest minimum period among them is the one that gates the buttons. And while a subscription is still inside its free trial, the minimum period counts as met, so a customer in a trial can still cancel.
The Min. Period column
↑ Back to topProducts > All Products gains a Min. Period column just after Price, so you can see your commitments at a glance without opening each product.
What it shows depends on the product:
- A product sold on subscription plans shows the effective minimum across its plans, as a single number when they all agree and as a range when they do not.
- A variable or variable subscription product shows the smallest minimum among its variations.
- Any other subscription product shows the number that applies to it.
The column is empty for products that are not sold on subscription, and the whole column disappears if you turn Enable Cancelling off.
Shortcodes
↑ Back to topTwo shortcodes let you place the minimum period in your own content, such as a landing page or a custom product template.
[mpws_minimum_period] outputs the minimum period for a single product, in the same markup used above the Add to cart button. Add an id attribute to name a product, as in [mpws_minimum_period id="123"], or leave it off on a single product page to use the product being viewed. It outputs nothing for variable products and nothing while Enable Cancelling is off.
[mpws_minimum_period_table] outputs a two-column table. For a product sold on subscription plans, the rows are the plans. For a variable product, the rows are the variations. For a simple subscription product, there is one row. It accepts the same id attribute.
Use cases
↑ Back to topA gym membership with a three-month commitment. Set Default Minimum Period(s) to 3 under WooCommerce > Settings > Subscriptions. Every monthly membership product now requires the initial payment plus two renewals before the Cancel button appears. Turn on Show in Product Pages and Show as Subscription Meta so the commitment is visible before purchase and repeated in the confirmation email.
A box subscription where the annual plan is cheaper because it commits. On a product sold with a monthly plan and an annual plan, open each plan in the plan dialog. Set the monthly plan’s Minimum period to Set for this plan with a value of 1, so monthly subscribers can leave at any time. Set the annual plan to Set for this plan with a value of 2. Turn on Show in Product Pages so the difference shows next to each option while the customer chooses.
One free product in a store that otherwise commits. Keep the store-wide default at 3, then open the free trial product and set Cancelling to Override storewide settings with Minimum Period(s) of 0. That product can be cancelled immediately while everything else keeps its commitment.
Tiers with different commitments on a variable subscription. On a variable subscription with Basic, Plus, and Pro variations, set Cancelling to Override storewide settings on each variation and give Basic 1, Plus 3, and Pro 6. Add [mpws_minimum_period_table] to the product description so customers can compare the commitments in one place.
Stopping subscribers from parking a subscription instead of paying it. Set your minimum period as usual, then turn on Link Suspensions. Customers now see neither Cancel nor Suspend until they have paid the required periods, which closes the gap where someone suspends a subscription to avoid the commitment. Check that WooCommerce Subscriptions’ Customer Suspensions setting is 1 or more, or the Suspend button was never there to begin with.
FAQ
↑ Back to topDoes the initial order count toward the minimum period?
Yes. The first payment is the first period. If you want a customer to renew once before they can cancel, set the minimum period to 2.
Which value applies if I set more than one?
The most specific one. A subscription plan’s own value wins. If the plan follows the product, the product’s own value is used. If the product does not set one either, the store-wide default applies.
Where do I set a minimum period for a subscription plan?
In the same dialog you use to add or edit the plan: on the product’s Subscriptions tab for a product’s own plans, or under WooCommerce > Settings > Subscriptions for store-wide plans. This needs WooCommerce Subscriptions 9.0 or higher.
Can I configure minimum periods for variable subscription products?
Yes. Each variation has its own Cancelling fields under the variation’s pricing options. A variation with nothing set follows the parent product, and then the store-wide default.
What happens if a customer buys a subscription-plan product as a one-time purchase?
Nothing. There is no subscription to cancel, so no minimum period is shown in the cart, at checkout, or on the order.
Will this affect subscriptions that already exist when I activate the extension?
Yes. The check counts the payments a subscription has already completed, so existing subscriptions are measured against the minimum period you set, just like new ones. A subscription that has already paid enough periods is unaffected.
What happens during a free trial?
The minimum period counts as met while the subscription is still in its trial, so a customer can cancel during the trial. Once the trial ends, the normal rule applies.
What if a subscription contains several products with different minimums?
The largest minimum among them applies to the whole subscription.
Does turning off Enable Cancelling remove the minimum periods I set?
No. The values stay on your products and plans. The setting simply hides the Cancel button for everyone and hides the extension’s fields and messages while it is off. Turn it back on and everything reappears as it was.
Does hiding the Cancel button stop me from cancelling a subscription as the store owner?
No. This affects the customer-facing My Account page only. You can still cancel or change any subscription from WP Admin.
Can I read or change minimum periods from an AI assistant?
Yes. The extension registers abilities with the WordPress Abilities API on WordPress 6.9 or higher, covering the store-wide settings, per-product and per-plan values, and whether a given subscription may be cancelled yet. Any plugin that consumes the Abilities API can expose them, and which of them an assistant may actually use is controlled in that plugin, not here. Every ability requires the manage_woocommerce capability.
Does uninstalling remove my settings?
No. The extension leaves its options and product meta in place when you delete it, so reinstalling picks up where you left off.
Developer documentation
↑ Back to topResolution logic lives in Minimum_Periods_For_Woocommerce_Subscriptions_Resolver. Its static methods are the single source of truth for both the admin screens and the customer-facing hooks, so extensions should call them rather than reading meta directly.
Key methods: Resolver::get_storewide_settings() returns the typed settings array, Resolver::resolve_minimum_periods( $product, $plan, $storewide ) returns the effective value plus the level that supplied it, and Resolver::evaluate_subscription( $subscription ) returns the full evaluation of one subscription, including payment_count, minimum_periods, remaining_periods, minimum_period_met, in_free_trial, can_cancel, and can_suspend.
Filter hooks
↑ Back to topmpws_product_types
Filters the legacy product type slugs treated as subscription products. Defaults to array( 'subscription', 'subscription_variation', 'variable-subscription' ). Fires inside Resolver::get_legacy_product_types(), which runs on every eligibility check.
Soft-deprecated in 3.0.0. It is still honored and raises no deprecation notice, but it now only extends the legacy product type list. Products sold on WooCommerce Subscriptions 9.0+ subscription plans are recognized regardless of their type, so adding a type here has no effect on plan products and removing one does not hide them.
add_filter(
'mpws_product_types',
function ( $types ) {
$types[] = 'my_custom_subscription_type';
return $types;
}
);The extension registers no action hooks of its own.
Storage
↑ Back to topStore-wide settings are wp_options rows, all autoloaded:
| Option | Type | Default |
|---|---|---|
mpws_allow_cancelling | yes / no | yes |
mpws_allow_cancelling_periods | integer as string | 1 |
mpws_show_paid_periods_myaccount | yes / no | no |
mpws_show_minimum_periods_singleproduct | yes / no | no |
mpws_show_minimum_periods_checkout | yes / no | no |
mpws_show_minimum_periods_myaccount | yes / no | no |
mpws_show_minimum_periods_meta | yes / no | no |
mpws_link_suspensions | yes / no | no |
mpws_cleanup_version | version string | absent until an update runs |
Products and variations carry two meta keys, exposed as Resolver::META_MODE and Resolver::META_PERIODS:
mpws_allow_cancelling, eitheruse-storewideoroverride-storewide.mpws_allow_cancelling_periods, the integer value used when the mode isoverride-storewide.
Per-plan values use the same two keys inside the plan arrays WooCommerce Subscriptions persists, in _wcsatt_schemes product meta for product plans and the wcsatt_subscribe_to_cart_schemes option for store-wide plans. Reusing the keys means the values survive plan copy, reorder, and export or import without extra work.
The plan a line item was bought on is read from _wcsatt_scheme item meta, falling back to the legacy _wcsatt_scheme_id. Plans are matched on either their id or the legacy {interval}_{period}[_{length}] key, so stores carrying both kinds of data resolve correctly.
The extension creates no database tables. Uninstalling leaves options and meta in place.
REST API
↑ Back to topThe extension does not register routes of its own. It adds two fields to the subscription plan endpoints WooCommerce Subscriptions exposes, through register_rest_field() on the product_subscription_plan and subscription_plan object types:
mpws_allow_cancelling, string, enumuse-storewideoroverride-storewide.mpws_allow_cancelling_periods, integer, minimum 0.
Both are readable and writable in the view and edit contexts on:
POST|PUT /wc/v3/products/{product_id}/subscription-plans[/{plan_id}]
POST|PUT /wc/v3/subscriptions/storewide-plans[/{id}]Because the plan controllers copy a fixed field list out of the request before the save filters run, the request is stashed on rest_request_before_callbacks and read back in wcsatt_processed_scheme_data and wcsatt_processed_cart_scheme_data. Responses are decorated on rest_request_after_callbacks rather than rest_post_dispatch, so in-process rest_do_request() calls carry the fields too.
Abilities API
↑ Back to topOn WordPress 6.9 or higher the extension registers eight abilities under the minimum-periods/ namespace, in the woocommerce category. Every one uses the same permission callback, which requires manage_woocommerce, and every one sets show_in_rest.
| Ability | Annotations | Purpose |
|---|---|---|
minimum-periods/get-settings | readonly, idempotent | Read the store-wide settings, plus store-wide plans and their values. |
minimum-periods/update-settings | idempotent | Update store-wide settings. Only supplied fields change. |
minimum-periods/get-product-minimum-period | readonly, idempotent | Read one product or variation, with its variations or plans expanded. |
minimum-periods/set-product-minimum-period | idempotent | Set mode and value on a product or variation. |
minimum-periods/set-plan-minimum-period | idempotent | Set mode and value on a product plan or a store-wide plan. |
minimum-periods/list-configured-products | readonly, idempotent | List products and variations that override the store-wide value. Paginated, 50 per page maximum. |
minimum-periods/get-subscription-status | readonly, idempotent | Evaluate one subscription against its minimum period. |
minimum-periods/list-subscriptions | readonly, idempotent | List subscriptions with their evaluation. Filters: status, customer, product, locked_only. Paginated, 50 per page maximum. |
Registration is consumer-agnostic. The abilities go into the Abilities API whenever WooCommerce and WooCommerce Subscriptions are active, and nothing in the extension knows about any particular MCP plugin. The woocommerce ability category is registered by WooCommerce 10.3 and higher; on older stores the extension registers the same slug itself.
Markup and styling
↑ Back to topThe customer-facing markup is generated in one place, Minimum_Periods_For_Woocommerce_Subscriptions_Messages, and the class names are treated as a stable public surface for theming:
.mpws_minimum_periods, wrapping.mpws-labeland.mpws-product-period, used above the Add to cart button and by[mpws_minimum_period]..mpws-plan-minimum-period, appended to a subscription plan option on the product page..mpws_minimum_period_table, wrapping the[mpws_minimum_period_table]output.
Cart and checkout output goes through woocommerce_get_item_data, and order line item output through woocommerce_order_item_meta_start, so both inherit your theme’s styling for those areas.
Front-end hook points
↑ Back to topThe extension attaches to these WooCommerce and WooCommerce Subscriptions hooks. Unhooking any of them disables that piece of behavior.
wcs_view_subscription_actions, priority 11 removescancel, priority 12 removessuspend.woocommerce_subscription_before_actions, priority 99, renders the paid periods and minimum period rows.woocommerce_before_add_to_cart_button, renders the product page block.wcsatt_single_product_subscription_option_descriptionandwcsatt_single_product_options, append the minimum period to plan options in the radio and dropdown layouts.woocommerce_get_item_data, adds the cart and checkout line item data.woocommerce_order_item_meta_start, adds the order line item meta.
Plan dialog integration
↑ Back to topWooCommerce Subscriptions renders its plans UI in React and offers no extension point, so the Minimum period field is injected from outside by admin/js/mpws-subscription-plans.js. A MutationObserver injects the field into .wcsatt-plan-modal when it opens, an apiFetch middleware adds the values to the plan save request and records what the response returns, and the plans tables get the read-only Min. period column.
The script is written to fail quietly. If WooCommerce Subscriptions changes its markup, the field simply does not appear, and per-plan values can still be set through the REST fields or the abilities above.
