Subscriptions

Sell recurring plans with free trials, renew licenses on each payment and let customers manage their own subscriptions. This needs TierMint Pro.

What you need

• TierMint Pro, active next to the free TierMint plugin.
• Stripe connected under TierMint → Settings → Payments, the same connection one-time sales use. The Stripe payments page covers it. PayPal can bill subscriptions too: see PayPal payments.
• Four subscription events added to your Stripe webhook. See Add the subscription events to your Stripe webhook.

TierMint creates the Stripe customer, product and price for each subscription itself. You do not set up plans in the Stripe Dashboard.

Make a pricing tier recurring

Recurring billing is set on a pricing tier, not on the product. One product can mix one-time tiers and recurring tiers, and the buyer picks one.

1. Open TierMint → Products and edit the product.
2. Open the Pricing tab. Click Add price, or use an existing tier.
3. Turn on Subscription.
4. Fill in the fields below.
5. Click Save product.

Field	What it does
Subscription	Makes the tier recurring. It sets Minimum quantity and Maximum quantity (0 = unlimited) to 1, because a subscription is always bought once. A recurring tier with any other limits is refused when you save.
Billing period	Day, Week, Month or Year.
Billing interval	How many billing periods pass between charges. It must be at least 1. Month with an interval of 3 bills every three months.
Trial days	Free days before the first charge. 0 means no trial.
Same as billing interval	Makes the license last one billing cycle, so each paid renewal extends it. See How renewals keep the license valid.
Allowed switch targets	Shows on a saved recurring tier when the product has another saved recurring tier. The plan changes page explains it.

The License length list on the tier card belongs to the free plugin. A new tier starts on Lifetime, and turning on Subscription does not change it. Same as billing interval writes the matching length into that list: 1 month for a monthly tier, 3 months for a tier that bills every 3 months. The box shows ticked while the license length equals one billing cycle. While it is ticked, a change to the billing period or interval moves the license length with it. Untick it to clear the length. The License length list then asks you to pick one, and the product does not save until you do.

Turning Subscription off makes the tier one-time again. The tier keeps its license length and leaves every Allowed switch targets list.

The free plugin stores no billing schedule. Pro keeps the schedule of each recurring tier in its own table. If you deactivate Pro, its recurring tiers go off sale. See If you deactivate Pro.

What the buyer sees under a plan

Under each plan, the free plugin prints the license line and the activation line. TierMint Pro adds more lines to every recurring tier, after those two:

• The billing line, such as "Billed monthly" or "Billed every 3 months".
• The trial line, when the tier has trial days, such as "14-day free trial".

The lines show in the plan selector, the pricing table, the cart and the checkout summary. The cart and the checkout hide them when Show plan details is off. Nothing else hides them, because a recurring price should say how often it bills. The block and shortcode switches Show license length and Show activation limit control the first two lines only.

When the license length equals one billing cycle, Pro shows "License lasts as long as your subscription" in place of the license line. This applies only while the license line is shown.

How free trials work

Set Trial days on a recurring tier to give a free trial before the first charge.

With Stripe, the buyer enters a card at checkout, but nothing is charged. Stripe saves the card, and the first charge runs when the trial ends. The license is issued at checkout and is fully active during the trial. If the first charge fails, the subscription moves to past due and dunning starts.

What happens at checkout

A recurring tier has three checkout rules. A cart that breaks one is refused with the message in the table.

Rule	Message the buyer sees
A subscription is bought on its own, with no other item in the cart.	A subscription must be purchased on its own. Please check out the subscription separately.
The quantity is one.	A subscription can only be purchased once per checkout.
No discount code.	Discount codes cannot be applied to subscriptions yet.

The buyer pays on the same checkout page and card form as a one-time purchase. Without a trial, they confirm the first payment. With a trial, they confirm the card only.

How renewals keep the license valid

The payment gateway charges each renewal on its own schedule. When a renewal is paid, TierMint:

1. Records a completed order with the type Renewal under TierMint → Orders.
2. Extends the license to the end of the newly paid period, plus 3 days.

The 3 extra days cover a late webhook, so the license does not lapse while a renewal is still on its way. A developer can change the number with the tiermint_subscription_license_slack_days filter.

TierMint only extends a license that has an end date. A recurring tier with License length set to Lifetime issues a license that never expires, even after the subscription ends. A new tier defaults to Lifetime, so tick Same as billing interval when you make the tier recurring.

The activation limit comes from the tier, the same as for a one-time purchase. It does not change between statuses.

Subscription statuses

Each subscription has one status. The subscription manager shows it to the customer with the label in the first column.

Status	What it means
Pending	The subscription exists, but its first payment has not settled yet.
Trial	Inside a free trial. Nothing is charged yet, and the license is active.
Active	The last payment was paid.
Past due	A payment failed and the gateway is retrying it. The license keeps working for a grace period. See Failed payments and dunning.
Cancelled	The subscription has ended.
Expired	The first payment never completed, or the gateway marked the subscription unpaid or expired.

Cancelled and Expired are final. A subscription in either status never becomes active again, so the customer buys a new one. Past due returns to Active as soon as a retried payment succeeds.

Where you see subscriptions

TierMint has no subscription list in wp-admin. You see subscription activity in these places:

• TierMint → Orders lists each paid renewal as an order of type Renewal.
• TierMint → Analytics reports recurring revenue and churn. The analytics page explains the numbers.
• Your Stripe Dashboard, or your PayPal account, holds the subscription itself.

Let customers manage their subscription

Customers manage subscriptions on their own storefront page. It is not a tab of the account dashboard. Create it once:

1. Create a page, for example "Subscriptions".
2. Add the [tiermint_subscription_manager] shortcode. On an Elementor page, use the TierMint Subscriptions widget instead.
3. Publish the page and link to it from your menu or your account page.

[tiermint_subscription_manager title="Your subscriptions"]

The title attribute sets the heading. It defaults to "Your subscriptions", and an empty value hides it.

A visitor who is not logged in sees a Log in link, plus Create an account when your site allows registration. A logged-in customer sees one card per subscription, newest first. Each card shows the product, the status, the price and billing cadence, and the next renewal date. A trial also shows when the trial ends.

The buttons on a card:

Button	What it does
Cancel subscription	Asks the customer to confirm, then sets the subscription to end at the close of the current paid period. The card then says the subscription is set to end on that date and will not renew.
Resume subscription	Shows instead of Cancel subscription while a cancellation is pending. It undoes the cancellation, so the subscription renews as normal.
Update payment method	Opens Stripe's customer portal, where the customer changes the card on file. Card details never reach your site.
Switch to (plan name)	Shows under Switch plan when you allow plan changes. See Plan changes and proration.

The buttons need JavaScript. Without it, the page asks the customer to turn it on.

The buttons work for Stripe subscriptions only. For a PayPal subscription they answer: "This subscription is managed through PayPal. To change or cancel it, sign in to your PayPal account."

Cancellations and the license

TierMint never ends a license early when a subscription is cancelled. The license keeps working until its own end date: the last paid period plus the 3 extra days. Then it expires in the normal way.

This is the same whoever cancels:

• The customer, with Cancel subscription.
• You, in your Stripe Dashboard. Stripe tells TierMint through the webhook, and TierMint marks the subscription Cancelled.
• The buyer, in their PayPal account, for a PayPal subscription.

When a subscription becomes Cancelled, TierMint emails the customer that it has ended, with a resubscribe link. The dunning page covers that email.

The one exception is a payment that is never recovered. When dunning gives up, TierMint cancels the subscription and expires the license at the end of the grace period. See What happens when the grace period ends. If the gateway ends the subscription first, the license expires at once: see Failed payments and dunning.

Cancelling does not refund anything. To refund a charge, refund its order. The orders page explains refunds.

Add the subscription events to your Stripe webhook

Subscriptions use the same Stripe webhook endpoint as one-time sales. You add four events to it. Stripe's webhooks guide shows where endpoints live in the Dashboard.

1. In your Stripe Dashboard, open the webhook endpoint for https://yourstore.example/wp-json/tiermint/v1/webhooks/stripe.
2. Keep the events the free plugin needs: payment_intent.succeeded, payment_intent.payment_failed and charge.refunded.
3. Add the four events in the table below.
4. Save the endpoint.

Event	What TierMint does with it
invoice.payment_succeeded	Records the first payment, each renewal, and the charge for a plan upgrade.
invoice.payment_failed	Moves the subscription to past due and starts dunning.
customer.subscription.updated	Copies the status, the paid period and a pending cancellation from Stripe.
customer.subscription.deleted	Marks the subscription Cancelled.

Adding events to an endpoint keeps its signing secret, so TierMint's settings need no change. Do this for your test mode endpoint and your live mode endpoint.

If you deactivate Pro

Without Pro, the free plugin cannot bill a renewal. Deactivating Pro takes the recurring tiers off sale.

• Deactivation archives every active recurring tier and remembers which ones it archived. They are not sold while Pro is off.
• Activating Pro again puts those tiers back on sale.
• A tier you archived yourself stays archived.
• A tier you made active again by hand while Pro was off stays active and keeps its schedule. The free plugin sells it as a one-time tier until Pro is active again.
• On a network, network deactivation and network activation do this on every site.
• Activation also clears the schedules of tiers that were deleted while Pro was off.

If Pro is removed without being deactivated, for example when its folder is deleted, nothing archives the tiers. They stay active, and the free plugin sells each one once, as a one-time tier, at its price and license length. Archive them first if you do not want that.

Recurring tiers in the REST API

Each pricing tier in the products REST API (tiermint/v1/products) carries a recurring key while TierMint Pro is active. For a recurring tier it is an object:

"recurring": { "billing_period": "month", "billing_interval": 1, "trial_days": 0 }

billing_period is day, week, month or year. billing_interval is 1 to 255 and trial_days is 0 to 65535. The key is null on a one-time tier.

On a save, each tier row is handled by its recurring key:

Row	What Pro does
An object	Stores that schedule. The tier becomes recurring, or its schedule changes.
null	Makes the tier one-time.
No recurring key	Keeps the stored schedule of a tier that already exists, so a client that does not know Pro cannot wipe it. A new tier becomes one-time.

A recurring tier must have min_quantity and max_quantity set to 1, or the save is refused. The free plugin ignores subscription fields sent on the tier itself, such as a billing period or a trial length. Send them in recurring. Pro keeps the schedule in its own table, not in the free plugin's price table.

Common questions

Can a customer buy a subscription and another product together?

No. A subscription must be the only item in the cart, at quantity one. The customer checks out twice.

Can I give a discount code on a subscription?

No. Checkout refuses any discount code on a cart that holds a subscription.

What happens to the license when a renewal fails?

Nothing changes at once. The subscription moves to past due and the license keeps working through a grace period. If a retry succeeds, the license is extended as normal. Failed payments and dunning explains the full sequence.

What if my site is down when a renewal is paid?

Stripe retries a webhook delivery that fails, and the 3 extra days on the license cover a short delay. TierMint also runs an hourly check: it asks Stripe about any subscription whose paid period ended more than 48 hours ago and records a renewal that the webhook missed. This check needs your Stripe secret key.

Does cancelling a subscription refund the customer?

No. Cancelling stops future renewals only. Refund a charge from its order.

Can a customer change their card without cancelling?

Yes. Update payment method opens Stripe's customer portal, where they change the card. The subscription keeps running.