/wp-freemius

name: wp-freemius
description: "Use when integrating Freemius SDK into a WordPress plugin for monetisation — SDK bootstrap with fs_dynamic_init, feature gating with can_use_premium_code() / is__premium_only() / is_plan() / is_trial() / is_paying(), license management, free/pro dual-zip build using __premium_only__ file suffix, generating upgrade URLs with get_upgrade_url(), opt-in analytics dialog, multisite licensing, affiliate program, or debugging Freemius dashboard (Plans, Pricing, Licenses, Updates). Triggers: \"add Freemius to my plugin\", \"gate this feature behind pro\", \"show the pricing page\", \"check if user has a license\", \"Freemius not initialising\", \"can_use_premium_code()\", \"is_plan()\", \"is_trial()\", \"is_paying()\", \"fs_dynamic_init\", \"my_plugin_fs()\", \"__premium_only__ file\", \"set up free and pro versions\", \"Freemius opt-in dialog\", \"trial period setup\", \"license key validation\", \"monetise my plugin\", \"get_upgrade_url()\", \"Freemius affiliate\", \"is_org_compliant\", \"Freemius SDK error\", \"free and premium zip\", \"Freemius multisite\", \"Freemius GlotPress translations\". Not for: WooCommerce payments — use `wp-woocommerce`; WP.org trialware compliance — use `wp-org-submission`."

Freemius SDK Integration

> **Model note:** SDK bootstrap and basic feature-gating are pattern-matching (`haiku`). Trialware compliance audit and pricing-plan architecture decisions require careful judgment — use `sonnet` for those.

Integrate Freemius into a WordPress plugin for commercial distribution: SDK bootstrap, free/pro feature gating, license management, trials, pricing page, and the Freemius dashboard. Freemius handles payments, license keys, update delivery, and analytics.

When to use

• "Add Freemius to my plugin", "set up free/pro version", "implement license management".
• "Gate premium features behind a license", "add a trial period".
• "Create a pricing page", "set up a Freemius affiliate program".
• "Debug Freemius SDK not loading", "fix opt-in dialog not showing".
• "Configure Freemius for multisite licensing".

**Not for:** General WooCommerce payment flows — use `wp-woocommerce`. WP.org trialware compliance (Freemius-powered upsells must follow WP.org Guideline 5 — use `wp-org-submission`, which contains `references/trialware-compliance.md`).

Method

1. Create a Freemius account and app

1. Sign up at `https://freemius.com` 2. Create a new **Plugin** product in the Freemius dashboard 3. Note down: **Plugin ID**, **Public Key**, **Secret Key** 4. Configure pricing plans (Free, Pro, etc.) in the dashboard

2. Install the SDK

**Via Composer (recommended):**

composer require freemius/wordpress-sdk

**Manual:** Download from `https://github.com/Freemius/wordpress-sdk` and place in `vendor/freemius/`.

3. Bootstrap the SDK

Create `includes/freemius.php` (the Freemius singleton init file):

<?php
if ( ! function_exists( 'my_plugin_fs' ) ) {
    function my_plugin_fs() {
        global $my_plugin_fs;

        if ( ! isset( $my_plugin_fs ) ) {
            // Include the Freemius SDK
            require_once plugin_dir_path( __FILE__ ) . '../vendor/freemius/wordpress-sdk/start.php';

            $my_plugin_fs = fs_dynamic_init( [
                'id'             => '12345',                            // Plugin ID from dashboard
                'slug'           => 'my-plugin',                       // WP.org slug
                'type'           => 'plugin',
                'public_key'     => 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // Public key
                'is_premium'     => false,                              // true if this IS the premium build
                'has_premium_version' => true,                          // true if premium version exists
                'has_addons'     => false,
                'has_paid_plans' => true,
                'trial'          => [
                    'days'               => 14,
                    'is_require_payment' => false,                      // true = credit card required
                ],
                'menu'           => [
                    'slug'    => 'my-plugin',
                    'contact' => false,
                    'support' => false,
                ],
            ] );
        }

        return $my_plugin_fs;
    }

    // Init Freemius
    my_plugin_fs();

    // Hook Freemius after initial plugin setup
    do_action( 'my_plugin_fs_loaded' );
}

**Load from main plugin file:**

// At the top of my-plugin.php, before any premium-gated code
require_once plugin_dir_path( __FILE__ ) . 'includes/freemius.php';

4. Feature gating

Gate premium features consistently throughout the codebase:

// Check if user has an active paid plan (or trial)
if ( my_plugin_fs()->can_use_premium_code() ) {
    // Show/run premium feature
    require_once plugin_dir_path( __FILE__ ) . 'includes/class-premium-feature.php';
}

// Check if the premium code file is loaded (for the __premium_only__ pattern)
if ( my_plugin_fs()->is__premium_only() ) {
    // Always true when premium file is present
}

// Specific plan check
if ( my_plugin_fs()->is_plan( 'professional', true ) ) {
    // $true = or_greater: matches 'professional' and any higher plan
}

// Trial check
if ( my_plugin_fs()->is_trial() ) {
    echo 'Trial active: ' . my_plugin_fs()->get_trial_plan()->title;
}

// Free user upsell prompt
if ( ! my_plugin_fs()->is_paying() ) {
    // Show upgrade CTA
    $upgrade_url = my_plugin_fs()->get_upgrade_url();
}

**`__premium_only__` file pattern** — Freemius strips these files from the free build:

my-plugin/
├── includes/
│   ├── class-core.php              # Free + premium
│   └── premium/                    # Only in premium zip
│       └── class-advanced.php__premium_only__

5. Pricing page

Freemius generates a hosted pricing page. Embed in the plugin's admin:

add_action( 'my_plugin_fs_loaded', function()