Order Subscriptions

Order Subscriptions for WooCommerce allows your customers to turn any WooCommerce order or product into a subscription. Nothing to rebuild, no plans to maintain, every renewal reduces real stock, full customer self-service.

Upgrading from 1.0.x

↑ Back to top

Nothing needs to be done to upgrade, and no live storefront changes price because of it. Four things behave differently afterwards, and all four are deliberate.

Existing subscriptions keep renewing at their current price

↑ Back to top

Before this version the Subscribe & Save discount only ever applied to the first order. Subscriptions created then have no percentage stored on them, and keep renewing at full price until you set one on the subscription itself. Discounting them automatically would change what those customers are charged without them having agreed to it, so it does not happen on its own.

“Discount the first order” is set to match what your store already did

↑ Back to top

On upgrade this setting is switched on for a store that already has subscriptions, and off for a store that has none. An existing store therefore keeps charging exactly what it charged yesterday, while a new store starts with the discount on renewals only, which is the arrangement that gives customers a reason to stay.

The product page widget is on

↑ Back to top

It appears wherever a subscription could already be offered, so it does not widen what is eligible, it only moves the choice earlier. Turn it off under Front-end settings if you would rather customers decided at checkout.

Widget colours

↑ Back to top

Stores that have never saved the Front-end settings tab pick up the new green highlight. Stores that have saved it keep the colours they stored, because a saved settings page stores every field on it, not only the ones that were edited. The Reset appearance to defaults button on that tab clears them if you want the new defaults.

Upgrading to 1.2.x

↑ Back to top

Nothing needs to be done, and no live storefront changes price because of it. Three things behave differently afterwards.

The product widget’s side-by-side layout is gone

↑ Back to top

Every widget stacks. A store that had chosen side by side sees stacked after updating. The layout was already falling back to stacked at most real widths once the card carried a badge, a benefits list and a pack shot.

Subscription history starts empty

↑ Back to top

History is recorded from 1.2.0 onward. Anything that happened before that was written to the log and cannot be recovered, so an existing subscription shows nothing until its next status change or renewal.

Customers cannot add or remove products until you allow it

↑ Back to top

A store that already has subscriptions gets this switched off on upgrade: its customers could not change what was in the box yesterday, and an update is not the moment to hand them that. A store with no subscriptions yet gets it on, because nobody’s expectations are being changed and the feature is worth finding. Either way it is under General, What customers can change themselves.

Setup

↑ Back to top

The configuration lives under WooCommerce › Settings › Order Subscriptions, across seven tabs. Only the first is needed to go live; the rest are there when you want them. They run in the order a store is set up: the three that decide whether you can sell a subscription at all, then the three ways of giving something away, then the plumbing.

Step 1: General settings

↑ Back to top

The tab is grouped into panels, each named for what it controls.

• General settings: the master switch, off by default. Off means no new subscriptions can be taken out and existing ones stop renewing. Nothing is deleted, and renewals resume from the next due date when you switch it back on.
• Renewal frequencies: which periods a customer may choose (days, weeks, months, years) and the minimum and maximum they may pick within each.
• Renewal frequencies also sets the Proposed frequency and Proposed interval: the schedule a customer is offered before they choose one for themselves. It must be one of the frequencies you allow. A product can propose a different one on its Subscriptions tab.
• What customers can change themselves: five switches: change the schedule, skip a renewal, pause and resume, cancel, and add or remove products. Each one off means the customer contacts you instead.
• Reminders: whether to warn a customer before a renewal and how many days ahead, plus the two windows that govern unpaid payment-link renewals.
• Order settings: what a renewal order carries over from the original: fees, shipping pricing, and any extra order meta you want copied.
• Subscribe & Save: the percentage off for subscribing, whether the first order carries it, and how many orders keep it. Covered in full under Subscribe & Save below.
• Other settings: logging, and whether to delete the plugin’s settings when it is uninstalled.

Step 2: Front-end settings

↑ Back to top

Every word a customer reads, and how the subscribe widget looks. Wording is stored per language. Covered in full under Front-end wording and appearance below.

Step 3: Product & user restrictions

↑ Back to top

Controls which products may be subscribed to and which customers may subscribe.

• Include or exclude by product category, tag or brand
• Include or exclude by user role
• Exclude an individual product or variation with a checkbox on its edit screen

Step 4: Free products

↑ Back to top

Sets the rules for giving a product away with a subscription: what earns one, how many orders carry it, and what happens when a rule offers several.

Step 5: Seasonal gifts

↑ Back to top

Sets date windows, each giving a product on renewals created between two dates.

Include users (whitelist – has priority)

• Enable order subscriptions for user roles: Select one or more user roles. Only users with these roles will see the subscription widget. If left empty, all logged-in users can access subscriptions (subject to the exclusion rules below).

Exclude users

• Disable order subscriptions for user roles: Select one or more user roles to prevent from using subscriptions. Only applies when the Include users field is empty.

Note: Include rules always take priority over Exclude rules. If you set both, only the Include rules are evaluated.

Include products (whitelist – has priority)

• Allow only these product categories: Only products in these categories will be eligible.
• Allow only these product tags: Only products with these tags will be eligible.
• Allow only these product brands: Only products with these brands will be eligible (requires WooCommerce Brands or a compatible plugin).

Exclude products

• Exclude product categories: Products in these categories cannot be purchased as subscriptions.
• Exclude product tags: Products with these tags cannot be purchased as subscriptions.
• Exclude product brands: Products with these brands cannot be purchased as subscriptions.

Product-level exclusion

• Enable exclusion at product level: When enabled, a checkbox appears on the product edit screen (for simple products) and on each variation (for variable products) that lets you individually exclude a product or variation from order subscriptions. The meta key is _osfwc_exclude_from_order_subscriptions with values yes or no.

Step 6: Milestone gifts

↑ Back to top

Sets a free product at a delivery number you choose – the fifth, the tenth – for customers who are still subscribed when they reach it. Covered in full under Milestone gifts below.

Step 7: Gateway compatibility

↑ Back to top

Which of your payment methods may be used for subscriptions, and how each one renews. Covered in full under The Gateway compatibility screen below.

Front-end wording and appearance

↑ Back to top

Under WooCommerce → Settings → Order Subscriptions → Front-end settings. Everything on this tab is optional; leave a field empty and the plugin’s own wording is used.

Wording, per language

↑ Back to top

If your store runs more than one language, the tab shows a language switcher and every string is stored separately for each one. Switching language changes which set you are editing; one Save writes them all.

The strings cover the checkout widget (the table cell title, the subscribe label, the interval label, the frequency prefix), the Subscribe & Save wording (the label on the totals line and the badge text, both of which accept {percent}), the message shown to logged-out customers, and every label on the product widget including its list of benefits.

The product widget’s appearance

↑ Back to top

• Show the widget on product pages: off returns you to the pre-1.1.0 behaviour, where the choice is only made at checkout.
• Pre-selected option: whether the page opens on one-time purchase or on subscribe. One-time is the default.
• Show the discount badge, Show benefits, Show the discounted price: three independent switches.
• Let customers choose the schedule here puts the renewal schedule on the widget itself, so it is chosen before the item reaches the cart rather than at checkout.
• Allow a different schedule per product lets each product carry its own schedule, which is what makes one order able to create more than one subscription.
• Highlight colour: marks the option the customer has chosen: its border, its tick, and the ticks beside the benefits. Leave it empty to use your theme’s own colour.
• Saving colour: used only for the “Save X%” badge, drawn as dark text on a pale tint of the colour you pick so it stays readable whatever you choose.

Resetting the appearance

↑ Back to top

Reset appearance to defaults clears the stored badge, benefit, price and colour settings so they follow the plugin again. It is there because saving a settings page stores every field on it, not only the ones you edited, so a value saved on an older version keeps that version’s default until it is cleared. Your wording and the widget’s on/off switch are not affected.

Subscribe & Save

↑ Back to top

A percentage off every order the subscription places. Configured under General → Order settings.

The settings

↑ Back to top

• Enable Subscribe & Save discount: the master switch for the feature.
• Discount percentage: between 1 and 50. Calculated on the subtotal after any coupons.
• Discount the first order: whether the order that starts the subscription carries the discount too. Switch it off and the discount begins at the first renewal, so there is nothing to gain from subscribing and cancelling immediately.
• Discounted orders: how many orders carry the discount before the subscription returns to full price. Zero means every order, forever.

How the cap counts

↑ Back to top

The cap counts orders that have actually been paid, not renewals attempted. Whether the first order is one of them depends on the setting above: with Discount the first order on, the order that started the subscription uses one of the capped orders; with it off, it does not, and the count begins at the first renewal.

So a cap of 3 with first-order discounting on means the signup order and two renewals. The same cap with it off means three renewals.

Terms are fixed when the customer subscribes

↑ Back to top

The percentage, the first-order rule and the cap are all written onto the subscription at signup. Changing any of them afterwards affects new subscriptions only. Nobody who has already subscribed is ever repriced, in either direction.

This is also why a subscription created before 1.1.0 renews at full price: it has no percentage written on it. Set one on the subscription itself if you want it discounted.

Free products

↑ Back to top

Under WooCommerce › Settings › Order Subscriptions › Free products. A product given at no charge with a subscription.

Rules

↑ Back to top

A rule is a list of free products plus the conditions a subscribed product has to meet to earn them. Match by category, tag, brand or product, and optionally by what the cart is worth. Rules are read from the top down: a product earns the first rule it matches, so put the narrow rules above the general ones. A rule naming nothing applies to everything.

Rules asking the same of a product but at different cart values are read as a ladder rather than a list, so they are ordered by amount for you and can be written in any order.

When a rule offers several products

• Give one, the first that is available reads the list as an order of preference: a product that is out of stock is replaced by the next one that is not.
• Give all of them reads it as a set: an unavailable product is left out rather than replaced.
• Let the customer choose one puts the list in front of them on the product page and at checkout, with the first as the default. Their choice is locked to the subscription, and the rest of the list stays behind it as fallbacks, so a product that sells out later falls through to the next rather than leaving them with nothing.

How many orders carry one

↑ Back to top

Set a number of orders, and choose whether the order that starts the subscription counts. With the first order included and a cap of one, the free product goes out once and no renewal carries one.

A turn is spent by the order rather than by the product: a renewal whose free product was out of stock has still used one.

What is locked, and when

↑ Back to top

The products, the cap and the mode are locked to a subscription when it is created. Changing a setting afterwards governs subscriptions taken out from then on, and leaves existing ones exactly as their customer agreed to them. This is why a new rule does not reach a subscription that already exists.

Customers can decline

↑ Back to top

A customer can stop receiving the free product from My Account and keep their subscription. That cannot be undone: reinstating would have to promise whatever the store lists today, which is not what they agreed to.

On the product page

↑ Back to top

The subscribe option names the free product, and can show a cut-out image of it in the corner of the card. The image needs a transparent background; leave it empty and the product’s own photo is used.

Per product

↑ Back to top

A product can carry its own list on its Subscriptions tab, which is used instead of the rules for that product.

Seasonal gifts

↑ Back to top

Under WooCommerce › Settings › Order Subscriptions › Seasonal gifts. A product added free to every renewal created between two dates.

Independent of the free products: it does not count against their allowance, a customer who has stopped their free product still receives one, and a renewal can carry both.

Windows

↑ Back to top

Each window has a start date, an end date, a product and a quantity. Both days are included, read in the store’s own timezone. Give a window a name and the card and the read-back use it instead of a number.

Renewal orders only: a subscription bought during a window does not carry one on its first order, because the order the customer pays for is not the one that arrives on its own.

Windows do not repeat. A window that has passed stays where it is until you change its dates.

Two windows covering the same day both apply, and a renewal created then carries both products. The screen says so, naming the pair and the days they share.

Keeping it a surprise

↑ Back to top

Each window can carry a name for the customer, set per language. That name is what the line is called on their order and in their emails; your own order screens and the merchant copy of the email keep the product name, so whoever packs the box knows what goes in it. Leave it empty and everyone sees the product.

Stock

↑ Back to top

The screen estimates what a window will cost in stock, by walking the renewals due inside it. Simple products or a single variation only, as gifts: a variable product leaves nothing able to decide which variation ships.

Milestone gifts

↑ Back to top

Under WooCommerce › Settings › Order Subscriptions › Milestone gifts. A free product at a delivery you choose – the fifth, the tenth, the twenty-fifth – for customers who are still subscribed when they get there.

Where free products reward buying and seasonal gifts reward timing, this one rewards staying. It is counted separately from both, so a renewal can carry a free product, a seasonal gift and a milestone gift at once.

Milestones

↑ Back to top

Each milestone is a delivery number, a product, a quantity and the wording the customer sees. The first order counts as delivery one. Set 5 and the gift arrives with the fifth order the subscription has placed, that order included.

A milestone is earned by reaching that delivery, not by passing it. Add a milestone at 5 today and a subscription already on its eighth delivery does not suddenly owe one, because it did not stay for a promise that did not exist. It will reach any milestone you set above 8.

Owed until it can be given

↑ Back to top

If the product cannot be given on the delivery it was promised for – out of stock, or no longer purchasable – the milestone stays owed rather than being missed, and the gift goes out with the next renewal that can carry it. A cancelled renewal hands its milestone back the same way, so the customer does not lose it because a payment was reversed.

What the customer is told

↑ Back to top

Each milestone carries its own line for the customer, set per language, shown on the order and in the email for that renewal. Leave it empty and the gift simply arrives. Their account page counts down to the next milestone they have not reached, so it is something to stay for rather than a surprise nobody knew about.

Stock

↑ Back to top

Simple products or a single variation only, the same as the other two gift types: a variable parent leaves nothing able to decide which variation ships, so the product search will not offer one.

The product page widget

↑ Back to top

On any product that could be subscribed to, the customer is offered a choice before adding to the basket: buy once, or subscribe. It renders above the add-to-cart button.

Where it appears

↑ Back to top

On simple and variable products that pass your product and user restrictions. On a variable product the choice resolves per variation, so a product where only some variations are eligible offers the choice on those and not on the others.

It does not widen what may be subscribed to. A product that could not be subscribed to at checkout does not gain a widget.

What the customer sees

↑ Back to top

• Two options, one pre-selected according to your setting
• The subscribed price, with the one-time price struck through, when a discount applies
• A “Save X%” badge, if you have one configured and have left it switched on
• A short list of what subscribing gets them, built from what your settings actually allow so it never promises an action you have switched off
• The free product it earns, if any, named in a sentence of its own and optionally pictured as a cut-out in the corner of the card
• Where a rule offers several free products and you have chosen to let the customer pick, the choice itself
• The renewal schedule: either a note that it is chosen at checkout, or, when Let customers choose the schedule here is on, the schedule itself with the suggested ones offered as pills

If the customer is already subscribing

↑ Back to top

When the basket already contains a subscription, the widget says so and offers to add the product to that subscription rather than starting a second one.

Turning it off

↑ Back to top

Under Front-end settings, switch off Show the widget on product pages. Subscriptions still work exactly as before; the choice is simply made at checkout instead.

Per-product schedules

↑ Back to top

By default every subscribed item in an order renews together on one schedule. Switch on per-product intervals under Front end settings > Product widget and each product can carry its own.

Where the schedule comes from

↑ Back to top

The store’s own default is set under General › Renewal frequencies, as Proposed frequency and Proposed interval. That is what a customer is offered first anywhere a schedule is shown.

A product can override it on its Subscriptions tab. If Let customers choose the schedule here is on under Front-end settings, the customer can pick a different one on the product page before the item is in the cart, and change it afterwards from the cart.

One order, several subscriptions

↑ Back to top

A cart holding products on different schedules creates one subscription per schedule when the order is placed, each with its own renewal date, its own total and its own entry in My Account. The customer is told about it once rather than once per subscription.

The checkout shows one recurring total per schedule, on both the classic and the block checkout.

The product subscriptions tab

↑ Back to top

Every simple and variable product has a Subscriptions tab in its product data panel. Everything on it is optional: left alone, the product follows the store settings.

Proposed schedule

↑ Back to top

The renewal schedule this product is offered on, overriding the store’s Proposed frequency and Proposed interval. Choose Use the store setting to follow the store, which is what a new product does.

Which option starts selected

↑ Back to top

Whether this product’s widget opens on One-time purchase or on Subscribe, overriding the store setting under Front-end settings. Use the store setting is what a new product does, and the option names what following the store currently gives you.

Notes per schedule

↑ Back to top

A short line shown to the customer beside a particular schedule, so a monthly option can say “most popular choice” and a yearly one can say something else. One note per schedule, and only the schedules you write a note for carry one.

Benefit bullets

↑ Back to top

The list of what subscribing gets them, for this product only. Left empty, the product uses the store’s bullets, which are themselves built from what your settings allow. Write {auto_usps} on a line of its own to keep that inherited list and add your own lines around it, rather than replacing all of them: at store level it stands for the generated list, and on a product it stands for whatever that product would have shown without an override. It never stands for the Subscribe & Save line or the free product line, which are added in front of whatever you write and would otherwise appear twice. Written twice it expands both times and then removes the duplicates; expanding to nothing leaves no empty bullet.

Free products

↑ Back to top

A list of free products for this product alone. When it has one, it is used instead of the rules on the Free products tab, so a product can promise something the rules would not have given it.

Checkout experience

↑ Back to top

In the cart

↑ Back to top

Each eligible line offers a tick to subscribe to that item. Ticking one shows what it costs subscribed against what it costs once, with the one-time price struck through, and a Subscribe & Save line appears in the cart totals showing the saving on the items ticked.

A customer does not have to subscribe to everything. Subscribe to the coffee and buy the grinder once, in the same order: the ticked items renew on the customer’s schedule and the rest is an ordinary one-time purchase.

At checkout

↑ Back to top

A logged-in customer sees the subscription widget above the order totals:

• The subscribe option, with your wording
• A frequency and interval picker, limited to the periods and the minimum and maximum you allow
• The Subscribe & Save saving, if one applies
• What the next renewal will cost, shown whenever it differs from the order being placed, a mixed basket, a first order that carries no discount, or shipping that will be recalculated

Payment methods

↑ Back to top

Each payment method carries a short line saying how it will renew, so a customer knows before choosing whether renewals arrive automatically or as an email to pay. Any method you have disallowed for subscriptions disappears from checkout while the basket contains one.

Customers who are not logged in

↑ Back to top

Subscriptions need an account, so a logged-out customer sees a message inviting them to log in or register instead of the subscribe option. The wording is yours, on the Front-end settings tab.

After the order is placed

↑ Back to top

The order confirmation page shows a summary of the subscription that was created: what renews, how often, and when the next payment is due.

Customer self-service (My Account)

↑ Back to top

Customers get a Subscriptions section in My Account. Everything there is optional: each action can be switched off under General → What customers can change themselves, and off means the customer contacts you instead.

The list

↑ Back to top

Every subscription the customer has, with its status, what it contains, how often it renews and when the next payment is due.

A single subscription

↑ Back to top

Opening one shows its details, the items on it, the billing and delivery addresses, and the orders it has already placed. From here the customer can:

• Pause and resume: useful when they are overstocked
• Skip the next renewal, instead of cancelling
• Cancel
• Change the schedule: within the frequencies and limits you allow
• Update quantities
• Add a product to the next delivery only: anything in the shop, forgotten again once that renewal is paid
• Add a product to every delivery from now on, or remove one: only products you sell on subscription can join every delivery. Removing the last product cancels the subscription, and is refused where customers may not cancel
• Edit the billing and delivery addresses: before the next shipment goes out
• Stop the free product, keeping the subscription. It is offered only while a free product is actually coming, and it cannot be undone

Every action is confirmed by email to the customer and to you.

Available actions by status

↑ Back to top

Status	Available actions
Active	Pause, Skip Next, Cancel, Add or remove products, Stop the free product (if one is still coming)
Paused	Resume, Cancel
Cancelled	None (final state)

My Account endpoint configuration

↑ Back to top

The endpoint slugs for the subscriptions pages can be customized in WooCommerce → Settings → Advanced → Account endpoints:

• Order Subscriptions: The endpoint for the subscriptions list page (default: order-subscriptions).
• View order subscription: The endpoint for the single subscription detail page (default: view-order-subscription).

These endpoints are also registered with WPML and Polylang for translation.

Admin subscription management

↑ Back to top

Subscriptions list

↑ Back to top

Navigate to WooCommerce → Subscriptions (or WooCommerce → Order Subscriptions when WooCommerce Subscriptions is also active).

The subscriptions list shows all subscriptions in a sortable, filterable table with columns for:

• Subscription ID
• Customer name
• Status (Active / Paused / Cancelled)
• Frequency (e.g., “Every 2 Weeks”)
• Next payment date
• Order count
• Created date

Bulk actions are available: Activate, Pause, Cancel, and Delete.

Filters: Filter by status (Active, Paused, Cancelled, All).

Search: Search subscriptions by ID, customer name, or email.

Subscription detail / edit view

↑ Back to top

Click on a subscription ID or the View action to open the subscription detail page. Click Edit to enter edit mode.

The detail page shows:

• Subscription details: Status, subscription ID, base order link, customer, created date.
• Schedule: Current interval and frequency (editable in edit mode), next payment date (editable via date picker in edit mode), last payment date.
• Payment info: Payment gateway, gateway title, provider name, provider customer ID, failed payment retry count.
• Subscribe & Save: Discount percentage locked at subscription creation (if applicable).
• Items: Products from the base order with quantities. In edit mode, quantities can be changed, and products can be added or removed with a product search – to the next delivery only, or to every delivery from now on. Every change is recorded in the history against whoever made it.
• Addresses: Billing and shipping addresses stored on the subscription.
• Related orders: All orders linked to this subscription, with links to each order.
• Free products: What this subscription was promised, which of them is given when a rule offers several, and how many of its turns are used. It also says why there is none when there is none: never promised one, stopped by the customer, or the allowance spent. Those are three different answers and the box gives the right one.
• Seasonal gifts: Every seasonal gift this subscription has received, newest first, with the window it came from, the order it arrived on and the date.
• Milestone gifts: Every milestone this subscription has reached, with the delivery number it was earned at, the product given and the order it arrived on. Milestones still owed are listed too, with why they have not been given yet.
• History: Status changes, renewal orders created, failed payments and skipped deliveries, newest first, each with who did it and when. Kept from version 1.2.0 onward: anything that happened before that was written to the log and is not recoverable, so an older subscription starts with an empty history and fills as it goes.

Order metabox

↑ Back to top

On any WooCommerce order that is linked to a subscription (either the base order or a renewal order), an Order Subscriptions metabox appears in the order edit screen.

The metabox shows:

• Whether the order is the initial subscription order or a recurring renewal order
• Subscription ID (linked)
• Status
• Frequency
• Next payment date
• Failed payment count (if any)
• Total order count
• A “Related Orders” table showing the most recent orders linked to this subscription (up to 5, with a “View all” link)
• A Manage subscription button linking to the subscription detail page

Orders table – subscription icon column

↑ Back to top

A subscription icon column is added to the WooCommerce orders list table (both HPOS and legacy). Orders linked to a subscription show a colored icon indicating the subscription status:

• Green = Active subscription
• Purple = Paused subscription
• Red = Cancelled subscription

Clicking the icon opens the subscription detail page. You can also filter the orders list by subscription ID using the ?osfwc_subscription_id= URL parameter.

Subscription stats

↑ Back to top

Under WooCommerce › Subscription Stats. Revenue, signups, renewals and cancellations for a period you choose, each compared against the period immediately before it, so a number arrives with the context that makes it mean something.

Below that, the same period broken down by product, category, tag and brand, and the customers behind it. Export buttons take any of it to CSV.

On the WordPress dashboard

↑ Back to top

WooCommerce’s own Status widget carries five more rows: subscription signups and what they were worth, renewals and what they were worth, and cancellations, all for the month in progress. Each links through to this screen. The rows are absent on a store that has never had a subscription.

CSV export

↑ Back to top

From the subscriptions list page, click the Export CSV button to download a spreadsheet of your subscriptions. The export includes all subscription data: ID, status, customer info, schedule, payment details, next payment date, order count, and created date.

Email notifications

↑ Back to top

Eighteen templates in total: seven to you, eleven to the customer. All of them are managed under WooCommerce → Settings → Emails like any other WooCommerce email, and all of them can be overridden from your theme.

Sent when	To you	To the customer
A subscription is created	yes	yes
A subscription becomes active	yes	yes
A subscription is paused	yes	yes
A subscription is cancelled	yes	yes
A subscription is cancelled automatically after repeated failures	yes	yes
A subscription is changed	yes	yes
A renewal payment fails	yes	yes
A renewal is skipped	—	yes
A renewal is coming up	—	yes
A renewal needs paying by link	—	yes
A payment-link renewal is still unpaid	—	yes

Each one comes in HTML and plain text. The last two are new in 1.1.0 and are only ever sent for a payment method that cannot charge on its own; the timing of both is under General → Reminders, and setting either window to zero switches that email off.

Template overrides

↑ Back to top

All email templates can be overridden by copying them from plugins/order-subscriptions/templates/emails/ to your theme at yourtheme/woocommerce/emails/. Both HTML and plain text templates are provided.

Automatic recurring payments

↑ Back to top

A background check runs once an hour, looks for subscriptions whose next payment date has arrived, and processes them. It is scheduled through Action Scheduler, so you can watch it under WooCommerce → Status → Scheduled Actions.

What a renewal order contains

↑ Back to top

Each renewal is a new WooCommerce order built from the subscription’s current items, not a copy of the original order:

• The products and quantities currently on the subscription, priced at today’s prices
• Stock reduced, exactly as a normal sale reduces it
• The billing and delivery addresses currently on the subscription
• Coupons and fees, if you have chosen to carry them over
• Shipping, priced according to your recurring shipping setting
• The Subscribe & Save discount, if the subscription has one

Because it is built fresh each time, an edit the customer makes: a quantity, an address, the schedule, is reflected in the next renewal without anything else being touched.

Shipping on renewals

↑ Back to top

Under General → Order settings, Recurring shipping cost has two options:

• Keep the cost from the original order. The renewal ships at the rate the customer agreed to at signup, whatever your rates do afterwards. This is the default, and it is what existing subscriptions already do.
• Recalculate at current rates on every renewal. Shipping is priced fresh each time, so rate changes reach subscribers.

One exception applies whichever you choose: a subscription renewing only part of its original order always recalculates, because the stored cost covered items it no longer ships.

Subscribe & Save on renewals

↑ Back to top

The discount applies to every order the subscription places, including renewals, at the percentage locked to that subscription when it was created. Changing the setting later never reprices anyone who has already subscribed.

When the gateway charges automatically

↑ Back to top

The order is created, the customer’s saved payment method is charged, and the order completes. They receive your usual order emails. Nothing else happens.

When the gateway renews by payment link

↑ Back to top

1. The renewal order is created with a status of pending payment.
2. The customer is emailed a link to pay that order.
3. If it is still unpaid after the number of days set in Manual renewal reminder (days), a reminder goes out.
4. If it is still unpaid after Manual renewal escalation (days), the renewal is treated as failed and the subscription follows the retry behaviour below.

Both windows are under General → Reminders. Set either to zero to switch that step off.

The escalation window applies to payment-link renewals only. A renewal on an automatic gateway is given a fixed fourteen days before being treated as abandoned, because some methods confirm slowly by design a SEPA Direct Debit can legitimately take a week to settle. Shortening the setting will not make those fail sooner, and it is not meant to.

When a payment fails

↑ Back to top

Failed renewals are retried on a backing-off schedule: after 12 hours, then 24, then 48. After the third failure the subscription is cancelled, and both you and the customer are notified at every step. Both halves of that are filterable from 1.2.2 – osfwc_payment_retry_limit for how many attempts, osfwc_payment_retry_date for how long to wait – so a store that would rather chase a customer for a week than for two days can.

Some failures are not worth retrying a deleted product, a deleted customer, an order that can no longer be built. Those cancel the subscription immediately rather than spending three attempts arriving at the same answer.

Protections you do not have to configure

↑ Back to top

• A subscription cannot be charged twice for the same cycle, even if two scheduler runs overlap.
• A renewal left pending or on hold for an unusually long time is escalated rather than left open indefinitely.
• If the subscription’s original order has been deleted, the subscription is cancelled and logged instead of retrying every hour.

Supported payment gateways

↑ Back to top

Every payment method you have enabled in WooCommerce can take a subscription. What differs is how the renewal is collected, and there are only two answers.

Renewed automatically

↑ Back to top

When the renewal falls due, the plugin charges the customer’s saved payment method and creates the order. Nobody is asked to do anything. This applies to the gateways with a built-in integration:

• Mollie (iDEAL, Bancontact, credit cards, SEPA Direct Debit, and the other methods Mollie offers)
• Stripe (via WooCommerce Stripe Gateway)
• WooPayments

The payment method is saved during the first checkout, so nothing extra is asked of the customer at signup either.

Renewed by payment link

↑ Back to top

Every other enabled method, including Cash on Delivery and Bank Transfer, renews by email. The renewal order is created as pending payment and the customer is emailed a link to pay it, with a reminder if it goes unpaid.

Nothing is lost by using a payment-link gateway. The subscription behaves identically; the customer just clicks once per renewal.

What the customer is told at checkout

↑ Back to top

Each payment method carries a short line saying how it will renew, so a customer choosing Bank Transfer knows an email is coming and a customer choosing Mollie knows one is not. The wording is filterable, see osfwc_renewal_method_label and osfwc_renewal_expectation_message in the developer reference.

If a gateway stops being available

↑ Back to top

A gateway is only treated as automatic while its own plugin is properly configured. If the integration is present but the gateway reports itself unavailable, a missing API key, credentials changed mid-configuration, the method drops to renewing by payment link instead of the renewal failing. Subscriptions keep running; they just collect differently until the gateway is working again.

The Gateway compatibility screen

↑ Back to top

Go to WooCommerce → Settings → Order Subscriptions → Gateway compatibility. The table lists every payment method you currently have enabled and how each one will behave.

Column	What it tells you
Payment method	The method as your customers see it, with its gateway ID underneath.
Provided by	Which plugin supplies it, and that plugin’s version.
Renewals	Automatic or Payment link. This is the only distinction that affects your customers.
Enabled for subscriptions	Whether the method may be used for a subscription at all. Automatic methods read Always on; everything else has a switch.

Choosing which methods may be used

↑ Back to top

Switch off any method you do not want used for subscriptions. It stays available for ordinary orders and disappears from checkout only when the basket contains a subscription.

The automatic gateways cannot be switched off here. They are the methods that renew without troubling the customer, so disallowing them would leave subscribers worse off. If you do not want one of them at all, disable the gateway in WooCommerce itself.

“Supports recurring natively”

↑ Back to top

Some payment-link methods carry this note. It means the gateway plugin tells WooCommerce it can store payment tokens, but there is no integration for it here yet, so this plugin does not attempt to charge it without the customer present.

The reason is deliberate. A stored token is not the same thing as permission to charge off-session, under strong customer authentication rules those are separate permissions, and charging on a token that was never authorised for it produces declines and chargebacks rather than payments. Until an integration exists that asks for the right permission at signup, the safe behaviour is a payment link. The note tells you an integration is plausible for that gateway, not that you should expect one today.

Verified against

↑ Back to top

Each built-in integration records the version of the gateway plugin it was last checked against. If you are running a much newer version of Mollie, Stripe or WooPayments than the one listed, renewals may well be fine, but it is the first place to look if automatic renewals start failing after a gateway update.

Request implementation

↑ Back to top

Every payment-link method carries a Request implementation link, which opens a short form asking which gateway you use. That is how the list of automatic gateways grows, and it is the most useful thing you can do if you want your own gateway renewing automatically.

Multilingual support

↑ Back to top

Compatible with WPML, Polylang, Weglot and GTranslate.

Every customer-facing string on the Front-end settings tab is stored per language, so the subscribe wording, the discount labels and the product widget’s benefits can differ between languages rather than being translated once for the whole store. See Front-end wording and appearance above.

Renewals processed in the background respect the customer’s language, so a renewal email arrives in the language they bought in rather than the site default.

Translations are bundled complete across 15 locales: Dutch (NL, BE) with a formal form, French (FR, BE, LU), and German (DE, AT, CH, BE, LU) with a formal form. Nothing is left half-translated.

HPOS compatibility

↑ Back to top

Fully compatible with High-Performance Order Storage. Every order query runs dual-path logic, so the plugin works whether your store uses HPOS or the legacy post-based storage, and keeps working if you switch between them.

WooCommerce Cart and Checkout blocks

↑ Back to top

Both blocks carry the full experience: the subscribe option, the per-item choice for mixed baskets, the frequency picker, the Subscribe & Save saving and the renewal total.

The integration is built on WooCommerce’s own extension points, the official slot fills and the Store API, rather than on the block markup, so it does not break when the blocks change internally.

Developer reference

↑ Back to top

A hundred and four documented hooks: 49 actions and 55 filters. Every one carries the version it arrived in and what it is passed.

Actions & hooks

↑ Back to top

A hundred and six documented hooks: 49 actions and 57 filters. Every one carries the version it arrived in and what it is passed.

Subscription lifecycle

↑ Back to top

Status, schedule and the dates a subscription runs on. 20 hooks: 16 actions, 4 filters.

Scheduling

↑ Back to top

How much work each scheduled run takes on. 3 hooks: 1 actions, 2 filters.

Renewal orders

↑ Back to top

What a renewal order is built from, and what it carries. 10 hooks: 3 actions, 7 filters.

Payments and gateways

↑ Back to top

Taking the money, and what happens when it does not arrive. 24 hooks: 6 actions, 18 filters.

Free products, seasonal and milestone gifts

↑ Back to top

Everything given away, and how it is chosen. 14 hooks: 5 actions, 9 filters.

Product widget, cart and checkout

↑ Back to top

What the customer is offered before they buy. 10 hooks: 0 actions, 10 filters.

My Account and customer actions

↑ Back to top

The customer’s own screens, and what they are allowed to do there. 15 hooks: 11 actions, 4 filters.

Emails

↑ Back to top

What each email contains, and when the customer gets one. 7 hooks: 4 actions, 3 filters.

Plugin lifecycle

↑ Back to top

Activation, deactivation and uninstall. 3 hooks: 3 actions, 0 filters.

Template overrides

↑ Back to top

Front-end and email templates can be overridden by copying them from the plugin’s templates/ directory into your theme. There are two override locations, depending on the template.

Front-end templates

↑ Back to top

Override directory: yourtheme/osfwc/

Template	Override path
Product page widget	yourtheme/osfwc/frontend/product/subscription-widget.php
Cart item subscribe row	yourtheme/osfwc/frontend/cart/item-subscribe.php
Cart repeat note	yourtheme/osfwc/frontend/cart/repeat-note.php
Checkout recurring totals	yourtheme/osfwc/frontend/checkout/recurring-totals.php
Thank you page subscription summary	yourtheme/osfwc/frontend/checkout/thankyou-subscription.php
My Account subscriptions list	yourtheme/osfwc/frontend/myaccount/subscriptions.php
My Account subscription detail	yourtheme/osfwc/frontend/myaccount/view-subscription.php

Note the frontend/ segment, it is part of the path inside your theme, not just inside the plugin.

Email templates

↑ Back to top

Override directory: yourtheme/woocommerce/, the same place WooCommerce’s own emails are overridden.

• HTML emails: yourtheme/woocommerce/emails/osfwc-subscription-*.php
• Plain text emails: yourtheme/woocommerce/emails/plain/osfwc-subscription-*.php

Not overridable

↑ Back to top

The checkout widget and the guest call-to-action are loaded directly rather than through the template system, so they cannot be replaced from a theme. Use the Front-end settings tab to change their wording, and the osfwc_* filters for anything further. The admin templates: subscription details, the gateway compatibility table and the analytics dashboard are not overridable either.

Adding your own gateway integration

↑ Back to top

A gateway renews automatically when an integration exists that can charge it without the customer present. Three ship with the plugin. You can add your own.

Extend the base integration class and register it on osfwc_register_gateway_integrations:

add_action( 'osfwc_register_gateway_integrations', function ( $manager ) {
    $manager::register_integration( new My_Gateway_Integration() );
} );

The manager is passed as a class name, not an instance, because registration happens through a static method.

Your class extends OSFWC\Gateways\Integrations\GatewayIntegration and tells the plugin which gateway it handles, whether it is currently able to charge, and how to take a payment for a renewal order. Set $verified_against to the version of the gateway plugin you tested against; it is shown on the Gateway compatibility screen so drift is visible rather than discovered by a failed renewal.

If your integration reports itself unavailable, missing credentials, for instance, the gateway falls back to renewing by payment link rather than the renewal failing.

Internal tiers

↑ Back to top

The osfwc_gateway_tier filter reports one of three values. certified means an integration is present and able to charge. tokenized means the gateway stores payment tokens but has no integration here; it renews by payment link, because a stored token is not permission to charge off-session. manual is everything else. Only the first behaves differently from the customer’s point of view.

Logging and troubleshooting

↑ Back to top

When logging is enabled, the plugin writes to WooCommerce’s built-in log system. Navigate to WooCommerce → Status → Logs to view log files.

Log files are organized by category:

Log file	Contents
osfwc-subscriptions	Subscription creation, status changes, schedule updates
osfwc-orders	Recurring order creation, validation, shipping
osfwc-gateways	General gateway processing
osfwc-gateway-mollie	Mollie-specific API calls and responses
osfwc-gateway-stripe	Stripe-specific API calls and responses
osfwc-gateway-woocommerce_payments	WooPayments-specific API calls and responses
osfwc-general	Plugin activation, scheduler, and general events

Common questions

↑ Back to top

A customer received an email asking them to pay for a renewal. Their payment method renews by payment link rather than automatically. Check the Gateway compatibility screen to see which of your methods do which.

A payment method has disappeared from checkout. It is disallowed for subscriptions and the basket contains one. Re-enable it on the Gateway compatibility screen, or leave it off if that was deliberate, it still appears for ordinary orders.

An existing subscriber is not getting the discount. Subscriptions created before 1.1.0 have no percentage stored on them. Set one on the subscription itself.

The widget looks wrong after an update. A saved settings page stores every field on it, so colours saved on an older version keep that version’s defaults. Use Reset appearance to defaults on the Front-end settings tab.

Renewals are not running at all. Check WooCommerce → Status → Scheduled Actions for the hourly check, and confirm the master switch under General settings is on.

A subscription is not getting its free product. Open the subscription and read the Free products box. It says which of three things is true: nothing was promised when the subscription was created, the customer stopped it, or the allowance is spent. Changing the store setting does not reach a subscription that already exists.

The history is empty on an older subscription. History is recorded from 1.2.0 onward. Anything before that was written to the log and cannot be recovered. It fills from the next status change or renewal.

The product widget looks different after updating to 1.2.x. The side-by-side layout was removed and every widget now stacks. If you had chosen side by side, this is why.

Minimum requirements

↑ Back to top

• WordPress 5.6 or greater
• WooCommerce 4.0.1 or greater
• PHP 7.4 or greater