Install
Upload it under Plugins → Add New Plugin → Upload Plugin, then activate.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/zeeshanraza-official/wpcalibrate-subscriptions/releases/download/v1.0.0/wpcalibrate-subscriptions-1.0.0.zipA production-ready standalone subscription and recurring billing engine built natively for WooCommerce. Empower your store to sell simple subscriptions, variable subscription tiers, and flexible Subscribe & Save recurring discounts—with zero dependency on proprietary WooCommerce Subscriptions.
Table of Contents
- About the Plugin
- Key Features
- Architecture & Database Design
- Installation & Requirements
- How to Use (Merchant Guide)
- Method & Renewal Mechanics
- Developer Docs, Hooks & REST API
- Automatic Dashboard Updates
- Changelog
- License
About the Plugin
WPCalibrate Subscriptions was engineered from the ground up for merchants and developers who demand a clean, high-performance recurring billing engine for WooCommerce without vendor lock-in or licensing bloat.
- 100% Independent Engine: Does not require, copy, or reverse-engineer WooCommerce Subscriptions. Operates on its own high-throughput database tables while generating standard WooCommerce parent and renewal orders.
- High-Performance Order Storage (HPOS): Built with native support for WooCommerce custom order tables (
wc_orders), fully bypassing legacywp_posts/wp_postmetaorder bottlenecks. - Cart & Checkout Blocks Native: First-class support for both modern WooCommerce Block-based checkouts and classic shortcode templates.
- Stripe Off-Session Integration: Native off-session PaymentIntents with 3D Secure / SCA customer recovery flows and cryptographic HMAC-SHA256 webhook verification.
- Dashboard Updates: Integrated GitHub release updater allowing instant one-click plugin updates directly in WordPress (
Plugins > Updates).
Key Features
🔄 Flexible Subscription Product Types
- Simple Subscriptions: Sell access, memberships, software licenses, or recurring boxes with daily, weekly, monthly, or yearly cadences.
- Variable Subscriptions: Different billing intervals, trial periods, and pricing tiers per variation.
- Subscribe & Save (Amazon-style): Allow shoppers to choose between standard one-time purchase or a recurring subscription discount (e.g., 5% off every month).
- Free Trials & Sign-up Fees: Configurable initial trial periods (days, weeks, months, years) and one-time registration fees.
- Billing Cycle Limits: Set subscriptions to automatically expire after a predetermined count of renewals (or run indefinitely until cancelled).
💳 Robust Payment Processing
- Automatic Off-Session Renewals: Seamlessly charges customer payment methods in the background via Stripe PaymentIntents (
off_session=true). - SCA / 3DS Authentication Recovery: When a bank requires Strong Customer Authentication, the subscription safely transitions to
on-holdand notifies the customer with a secure link to authorize payment. - Manual Invoiced Renewals: Customers can pay each cycle manually via standard WooCommerce checkout with automated invoice reminders.
- Automated Webhook Sync: Syncs charge disputes, refunds, and cancellations directly from payment providers.
🛡️ Enterprise Concurrency & Reliability
- Action Scheduler Integration: Renewal processing and background maintenance run asynchronously without slowing down frontend customer traffic.
- Strict Billing Event Idempotency: Cryptographically unique event keys (
renewal_{sub_id}_{timestamp}) and distributed mutex locks prevent parallel workers from ever double-charging customers. - Optimistic Concurrency Control: Versioned record locking (
versioncolumn) prevents race conditions when merchants and customers modify subscription states simultaneously. - Exponential Payment Retries: Configurable multi-attempt retry schedules with configurable backoff timing (e.g. 12h, 24h, 48h, 72h) before terminal status transitions.
👤 Customer Self-Service & Admin Management
- Customer My Account Integration: Customers can view renewals, update billing/shipping addresses, change payment methods, pause/resume, or cancel subscriptions.
- Comprehensive Admin Table: Search by ID, customer name, email, or order ID; filter by status (Active, On-Hold, Paused, Pending Cancellation, Cancelled, Expired, Failed); manual one-click renewals.
- Transactional Emails: Native WooCommerce customer notifications for subscription activation, renewal confirmations, payment retry alerts, and renewal payment failures.
Architecture & Database Design
WPCalibrate Subscriptions isolates recurring contract definitions from generic WordPress posts using three dedicated, indexed custom database tables:
erDiagram
wp_wpcal_subscriptions ||--o{ wp_wpcal_subscription_items : contains
wp_wpcal_subscriptions ||--o{ wp_wpcal_subscription_events : logs
wp_wpcal_subscriptions }|--|| wp_wc_orders : references_parent
wp_wpcal_subscriptions {
bigint id PK
varchar status
bigint customer_id
bigint parent_order_id
int billing_interval
varchar billing_period
int trial_length
varchar trial_period
decimal recurring_total
datetime next_payment_date_gmt
datetime trial_end_date_gmt
datetime cancelled_date_gmt
varchar payment_method
int retry_count
int version
}
wp_wpcal_subscription_items {
bigint id PK
bigint subscription_id FK
bigint product_id
bigint variation_id
varchar name
int quantity
decimal subtotal
decimal total
}
wp_wpcal_subscription_events {
bigint id PK
bigint subscription_id FK
varchar event_type
varchar event_key UK
text message
datetime created_at_gmt
}
Installation & Requirements
System Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| WordPress | 6.4+ | 7.1.3+ |
| WooCommerce | 8.5+ | 11.2+ |
| PHP | 8.2+ | 8.3+ |
| Database | MySQL 8.0+ / MariaDB 10.5+ | MySQL 8.0+ |
Installation Steps
- Download the latest
wpcalibrate-subscriptions-1.0.0.zipfrom Releases. - In your WordPress admin, navigate to Plugins > Add New Plugin > Upload Plugin.
- Choose the ZIP file and click Install Now, then click Activate Plugin.
- Navigate to WPCalibrate > Subscriptions in your admin sidebar.
How to Use (Merchant Guide)
1. Setting Up Subscription Products
- Navigate to Products > Add New (or edit an existing product).
- In the Product Data box, open the Subscription tab.
- Check Subscription Product.
- Configure your:
- Recurring Price: Charge per interval (leave blank to use the product's regular price).
- Billing Interval & Period: e.g. every
1 Month,2 Weeks, or1 Year. - Free Trial: Optional duration before the first payment is scheduled.
- Signup Fee: Optional one-time fee charged immediately at checkout.
- Expire After: Optional cycle limit (leave empty for indefinite renewals).
- Click Publish or Update.
2. Setting Up Subscribe & Save
- In any standard WooCommerce product, open the Subscription tab.
- Check Enable Subscribe & Save.
- Enter the Recurring Discount (%) (e.g.
5for 5% off). - Shoppers will now see a choice between One-time purchase at regular price and Subscribe & Save at the discounted price on the product page.
- In the cart and checkout, the customer is charged the discounted price immediately with zero sign-up fees or accidental free trials.
3. Payment Gateway Configuration
- Go to WPCalibrate > Subscriptions > Settings > Payment Gateways.
- Enable Stripe Automatic Renewals:
- Provide your Stripe Publishable Key, Secret Key, and Webhook Secret.
- Add the webhook endpoint
https://your-site.com/wp-json/wpcalibrate-subscriptions/v1/stripe/webhookto your Stripe Dashboard.
- (Optional) Enable Manual Renewals if you want to allow customers to receive email invoices and pay renewals via standard checkout.
4. Managing Subscriptions in WP Admin
- View all subscriptions under WPCalibrate > Subscriptions.
- Filter by status tabs:
All,Active,On-hold,Paused,Pending cancellation,Cancelled,Expired,Failed. - Click on any subscription to view full line items, renewal history, attached WooCommerce orders, next payment date, and transaction logs.
- Perform administrative actions: Charge Renewal Now, Pause, Resume, or Cancel.
5. Customer My Account Self-Service
Customers can manage their recurring subscriptions under My Account > Subscriptions:
- View billing intervals, recurring totals, and upcoming payment dates.
- Pause or resume active subscriptions (if permitted in admin settings).
- Request cancellation (effective immediately or at the end of the paid billing period).
- Update shipping and billing addresses for recurring deliveries.
Method & Renewal Mechanics
Action Scheduler Background Processing
Every subscription calculates its deterministic UTC next payment date using calendar-aware month-end and leap-year clamping (e.g. Jan 31 clamps to Feb 28/29, Mar 31 clamps to Apr 30). Background workers execute via Action Scheduler:
wpcal_sub_process_renewal: Processes scheduled recurring charges.wpcal_sub_process_retry: Handles backoff retries for soft-declined cards.wpcal_sub_process_expiration: Completes subscriptions reaching cycle limits.wpcal_sub_daily_maintenance: Reconciles overdue renewals and system health.
Idempotency & Concurrency Protection
To prevent accidental double charges during network drops or duplicate worker invocations:
- Each renewal action generates a unique event key:
renewal_{subscription_id}_{timestamp}. - Before processing, an atomic record is inserted into
wpcal_subscription_events. If the key already exists, execution immediately aborts. - Transient mutex locks are held during order creation (
wp_wc_orders) and tokenized gateway charging.
Smart Failed Payment Retries
When an off-session charge fails:
- Soft Declines (insufficient funds, temporary gateway downtime): The subscription enters
on-holdand enters an automated retry queue following your configured backoff intervals. - Hard Declines (expired card, lost/stolen, fraud): The retry schedule terminates immediately, preventing unnecessary gateway penalties, and sends an urgent update-payment notification to the customer.
Developer Docs, Hooks & REST API
REST API Endpoints
All endpoints are registered under /wp-json/wpcalibrate-subscriptions/v1:
| Method | Route | Description | Capability Required |
|---|---|---|---|
GET |
/subscriptions |
List subscriptions (with status/customer filters) | manage_woocommerce |
GET |
/subscriptions/<id> |
Retrieve subscription details & line items | manage_woocommerce |
POST |
/subscriptions/<id>/status |
Update subscription status (active, paused, cancelled) |
manage_woocommerce |
POST |
/stripe/webhook |
Stripe webhook receiver (HMAC verified) | Public (Signed) |
Action & Filter Hooks
Actions
// Fired immediately after a subscription is created from a checkout order
do_action( 'wpcal_sub_created', Subscription $subscription, WC_Order $order );
// Fired when a subscription status changes
do_action( 'wpcal_sub_status_changed', Subscription $subscription, string $old_status, string $new_status );
// Fired after a recurring renewal payment succeeds
do_action( 'wpcal_sub_renewal_success', Subscription $subscription, WC_Order $renewal_order );
// Fired when a recurring renewal payment fails
do_action( 'wpcal_sub_renewal_failed', Subscription $subscription, WC_Order $renewal_order, string $error_message );
Filters
// Filter grouped subscription line items before subscription creation
add_filter( 'wpcal_sub_group_order_items', function( array $groups, WC_Order $order ) {
return $groups;
}, 10, 2 );
// Modify retry interval schedule (in seconds)
add_filter( 'wpcal_sub_retry_intervals', function( array $intervals ) {
return [ 12 * HOUR_IN_SECONDS, 24 * HOUR_IN_SECONDS, 48 * HOUR_IN_SECONDS ];
} );
// Customize next payment date calculation
add_filter( 'wpcal_sub_calculate_next_payment_date', function( DateTimeImmutable $next_date, DateTimeImmutable $from_date, int $interval, string $period ) {
return $next_date;
}, 10, 4 );
Automatic Dashboard Updates
WPCalibrate Subscriptions includes a built-in GitHub release updater. When a new version is tagged and released on GitHub:
- WordPress detects the update during scheduled background checks (or via Dashboard > Updates > Check Again).
- An update notification appears in your Plugins list with release notes and changelog.
- Click Update Now to update the plugin directly from GitHub without needing FTP or manual re-uploads.
Changelog
[1.0.0] - 2026-10-21
- Initial Production Release.
- Standalone subscription engine with custom tables (
wpcal_subscriptions,wpcal_subscription_items,wpcal_subscription_events). - Full support for WooCommerce HPOS (High-Performance Order Storage) and Cart/Checkout Blocks.
- Simple Subscriptions, Variable Subscriptions, and Subscribe & Save product support.
- Stripe off-session automatic renewals with SCA/3DS recovery and HMAC webhook signature validation.
- Calendar-aware UTC date math with leap-year and month-end clamping.
- Action Scheduler background processing with idempotent renewal locks.
- Customer My Account subscriptions interface with pause/resume and self-service cancellation.
- Built-in GitHub Dashboard Updater integration for one-click WordPress updates.
- 36 automated unit and integration tests passing with 0 failures.
License
This plugin is licensed under the GNU General Public License v2.0 or later.
Copyright (c) 2026 WPCalibrate.
Releases
1 release. Each count is every asset in that release; expand a row for the breakdown.