OSubscribe v1.0.0-alpha

What OSubscribe does

Adds recurring-revenue infrastructure to WooCommerce: subscriptions, billing, dunning, retention flows, payment plans, customer portal, and analytics. Premium plugin, GPL-licensed code, sold once with lifetime updates.

Getting installed

From zero to first renewal

Plugin architecture

13 database tables

All prefixed with {prefix}osub_. Created on activation via OSub_DB::activate(). Indexes are tuned for the four hot queries: charges due in next N hours, subs in dunning, subs for a given user, and charges for a given subscription.

A 13th table (osub_subscription_items) sits in the same migration to keep multi-line subscriptions cleanly normalized.

Admin interface

A custom top-level menu (osubscribe) with submenus for every operational view. Themed to match OMailer (Inter Tight + JetBrains Mono + Instrument Serif, dark by default with light toggle, orange accent).

Settings reference

All settings stored in wp_options under key osub_settings. Defaults set on first activation; merge-safe on upgrade.

Subscription lifecycle

Subscriptions move through a small, well-defined state machine. Every transition fires osub/subscription/transitioned with the from + to state, plus a state-specific action.

PHP// Lifecycle hooks fire alongside the generic transitioned event.
do_action( 'osub/subscription/created',   $sub_id );
do_action( 'osub/subscription/renewed',   $sub_id, $charge_id );
do_action( 'osub/subscription/paused',    $sub_id );
do_action( 'osub/subscription/resumed',   $sub_id );
do_action( 'osub/subscription/cancelled', $sub_id, $reason );
do_action( 'osub/subscription/transitioned', $sub_id, $from, $to );

Billing engine

The cron tick runs every five minutes. It selects subscriptions where next_charge_at ≤ NOW() in batches of 50 (filterable via osub/scheduler/batch_size) and dispatches each to its gateway with a unique idempotency key.

Dunning engine

When a charge fails, OSubscribe enters the subscription into a dunning run (row in osub_dunning_runs) and schedules retries on a configurable schedule. Default is 4 attempts at 3, 5, 7, and 14 days.

PHP// Per-subscription retry schedule override
add_filter( 'osub/dunning/retry_schedule', function( $schedule, $subscription ) {
    if ( $subscription->amount_recurring() > 100 ) {
        return [ 2, 5, 9, 14, 21 ];
    }
    return $schedule;
}, 10, 2 );

// Outcome listeners
add_action( 'osub/dunning/recovered', function( $sub_id, $attempts ) { /* notify */ }, 10, 2 );
add_action( 'osub/dunning/exhausted', function( $sub_id, $last_failure ) { /* notify */ }, 10, 2 );

Save flows

When a customer hits cancel in the portal, OSubscribe presents the first eligible save flow offer. Each presentation is logged to osub_save_flow_runs with reason, offer payload, and outcome.

PHPuse Orravo\OSub\SaveFlows\Engine;

Engine::register([
    'name'     => 'Pause instead of cancel',
    'eligible' => fn( $subscription ) =>
        $subscription->interval_unit() === 'month'
        && $subscription->billings_completed() >= 3,
    'offer'    => [
        'type'          => 'pause',
        'duration_days' => 60,
        'headline'      => 'Take a 60-day break instead?',
    ],
]);

Payment plans

Sell a fixed-price item over a finite number of installments. Unlike a subscription, a plan has a known total and a clear end date. Access policy can revoke content if the customer defaults.

PHPuse Orravo\OSub\PaymentPlans\Plan;

Plan::save([
    'name'         => 'Annual Course, 4 payments',
    'total_amount' => 480.00,
    'currency'     => 'USD',
    'schedule'     => [
        [ 'amount' => 120, 'days_after_signup' => 0 ],
        [ 'amount' => 120, 'days_after_signup' => 30 ],
        [ 'amount' => 120, 'days_after_signup' => 60 ],
        [ 'amount' => 120, 'days_after_signup' => 90 ],
    ],
    'access_policy' => [ 'revoke_on_default' => true ],
]);

MRR analytics

A daily cron job rolls every active subscription and charge into osub_metrics_daily (one row per date). The Reports admin page reads only this table, so the dashboards are fast even on stores with many subscribers.

Rebuild the entire history from raw events with wp osub metrics rebuild --from=2026-01-01. Useful after schema migrations or backfills.

Self-service portal

A single shortcode ([osubscribe_account]) renders the customer’s portal: active subscriptions, billing history, payment methods, save flow entry. Requires the user to be logged in.

• Pause / resume: customer-initiated; logs to osub_schedule_changes
• Swap payment method: tokenized card update via the gateway’s SetupIntent flow
• Cancel: triggers any eligible save flow before completing
• Download invoice: per-charge PDF rendered from a template

WooCommerce integration

• HPOS-compatible: declares custom_order_tables compatibility on before_woocommerce_init
• Subscription product type: registered alongside Simple, Variable, Grouped
• WooCommerce My Account: a Subscriptions tab is added under /my-account/
• Order linkage: every charge can produce a paid WooCommerce order (parent_order_id on the subscription, order_id on the charge)
• Coupons: Woo coupons applied at checkout flow through to the recurring price (configurable: first cycle only vs. forever)
• Importer: OSub_Migration reads existing WooCommerce Subscriptions data and back-fills osub_subscriptions + osub_charges

Payment gateways

Register additional gateways through osub/gateways/register. The contract is small: implement charge( $subscription, $idempotency_key ) and verify_webhook( $request ).

Shortcodes

[osubscribe_account]

REST API endpoints

Base namespace: /wp-json/osub/v1/. Admin endpoints require osub_manage capability; /me/ endpoints require login.

Developer hooks

PHP// Bootstrap
do_action( 'osub/booted' );
do_action( 'osub/event', $event_name, $payload );
do_action( 'osub/event/' . $event_name, $payload );

// Subscription lifecycle
do_action( 'osub/subscription/created',     $sub_id );
do_action( 'osub/subscription/renewed',     $sub_id, $charge_id );
do_action( 'osub/subscription/paused',      $sub_id );
do_action( 'osub/subscription/resumed',     $sub_id );
do_action( 'osub/subscription/cancelled',   $sub_id, $reason );
do_action( 'osub/subscription/transitioned', $sub_id, $from, $to );

// Charges
do_action( 'osub/charge/attempted',  $sub_id, $charge );
do_action( 'osub/charge/succeeded',  $sub_id, $charge );
do_action( 'osub/charge/failed',     $sub_id, $charge );

// Dunning
do_action( 'osub/dunning/entered',   $sub_id, $run_id );
do_action( 'osub/dunning/recovered', $sub_id, $attempts );
do_action( 'osub/dunning/exhausted', $sub_id, $last_failure );

// Save flows
do_action( 'osub/save_flow/offered',  $sub_id, $flow_id, $offer );
do_action( 'osub/save_flow/accepted', $sub_id, $flow_id );
do_action( 'osub/save_flow/declined', $sub_id, $flow_id );

// Payment methods + magic links
do_action( 'osub/payment_method/updated', $user_id, $token_id );
do_action( 'osub/magic_link/consumed',    $user_id, $token, $purpose );

// Webhooks
do_action( 'osub/webhook/stripe', $event );
do_action( 'osub/webhook/paypal', $event );

// Gateway registration extension point
do_action( 'osub/gateways/register', $registry );

PHP// Skip a charge attempt entirely (postpones by 24 hours)
apply_filters( 'osub/charge/should_attempt', $bool, $subscription );

// Per-subscription retry schedule override
apply_filters( 'osub/dunning/retry_schedule', $schedule, $subscription );

// Cron tick batch size
apply_filters( 'osub/scheduler/batch_size', 50 );

WP-CLI surface

SHELL# Subscription operations
wp osub subscription show 1842
wp osub subscription pause 1842
wp osub subscription resume 1842

# Charge operations
wp osub charge retry 7321 --force

# Dunning
wp osub dunning queue

# Metrics
wp osub metrics rebuild --from=2026-01-01

# Migration (legacy WC Subscriptions)
wp osub migrate dry-run
wp osub migrate run --batch=200

# Demo / testing
wp osub seed-demo
wp osub tick

Versus the alternatives

Pricing model

One purchase, three tier sizes, lifetime updates. No subscriber-count tax. No per-charge fees. Buy once, install on the sites in your tier, get every future update free.

Changelog