The WordPress.org freemium trap: how to ship a Pro plugin without getting suspended

If you've ever thought about building a freemium WordPress plugin and
distributing the free version through WordPress.org, there's a compliance
rule that will catch you off guard.

You cannot ship locked features.

Not locked behind a license check. Not hidden behind an if (is_pro()).
Not greyed out with a tooltip saying "upgrade to unlock." The WordPress.org
guidelines call this trialware, and plugins that do it get suspended.

This is the architecture I built to solve it — for
Laterreta Migrator for Shopify,
a plugin that migrates Shopify stores to WooCommerce.

---

What the guidelines actually say

From the WordPress.org plugin guidelines:

Plugins may not contain functionality that is hidden or disabled and
waiting to be unlocked by a purchase or license.

The key word is contain. The code cannot be in the plugin at all — not
even dormant, not even behind a flag.

This rules out the most common freemium patterns:

// ❌ Not allowed on WP.org — code is present but locked
if ( has_valid_license() ) {
    download_images( $product );
}

// ❌ Also not allowed — feature exists but is gated
function download_images( $product ) {
    if ( ! is_pro() ) {
        show_upgrade_notice();
        return;
    }
    // actual code...
}

Both of these put Pro code inside the free ZIP. That's trialware.

The solution: hooks as a bridge
WordPress's hook system (add_filter / add_action / apply_filters /
do_action) gives you a clean way to make the free plugin extensible
without including the extension code.

The idea: the main plugin fires hooks at every point where Pro behaviour
could happen. In the free build, those hooks have no callbacks — they do
nothing. The Pro build ships extra files that register callbacks on those
hooks.

// In the main plugin (ships in BOTH free and Pro)
// Pro: add image fields to the GraphQL query
$image_fields = apply_filters( 'lmsf_graphql_image_fields', '' );

// Pro: do something after a product is imported
do_action( 'lmsf_after_product_imported', $postId, $product );
In the free build, apply_filters() returns the empty string default
and do_action() fires with zero listeners. No Pro code runs because
there's no Pro code present.

In the Pro build, extra files are included that register callbacks:

// Pro only: includes/pro/images.php  (absent from free ZIP)
add_filter( 'lmsf_graphql_image_fields', function( string $extra ): string {
    return $extra . "\nimages(first:10){ edges{ node{ url altText } } }";
});

add_action( 'lmsf_after_product_imported', function( int $postId, array $product ): void {
    lmsf_download_and_attach_images( $postId, $product['images']['edges'] ?? [] );
}, 10, 2 );

The Pro file is physically absent from the free ZIP. There's nothing
to unlock — the feature simply doesn't exist in that build.

Two ZIPs from the same source
The build script produces two completely different ZIPs from the same
codebase:

./build.sh # Pro ZIP — includes/pro/ copied in
./build.sh --free # Free ZIP — includes/pro/ deleted before packaging
The free ZIP goes to WordPress.org SVN. The Pro ZIP goes to the product
download on our site. Same source, different outputs.

# Simplified build logic
if $FREE_BUILD; then
    rm -rf "$STAGE_DIR/includes/pro"
    cp "$LICENSE_STUB" "$STAGE_DIR/includes/license.php"
else
    cp -r "$PLUGIN_DIR/includes/pro" "$STAGE_DIR/includes/pro"
    cp "$LICENSE_FILE" "$STAGE_DIR/includes/license.php"
fi

Every Pro feature follows the same pattern
Once the hook bridge is in place, adding Pro features is always the same
three steps:

1. Add a hook in the main plugin at the right extension point

// Main plugin: migration query builder
$extra = apply_filters( 'lmsf_graphql_product_extra_fields', '' );
$gql   = "query P { products { edges { node { id title {$extra} } } } }";

1. Create a file in includes/pro/ that registers a callback

// includes/pro/tags.php
add_filter( 'lmsf_graphql_product_extra_fields', function( string $extra ): string {
    return $extra . "\ntags";
});

add_action( 'lmsf_after_product_imported', function( int $postId, array $product ): void {
    lmsf_tags_apply( $postId, $product );
}, 10, 2 );

1. Build — the Pro file is included, the free file is not

Current Pro features and their hooks:

Feature Filter (adds fields) Action (saves data)
Image download lmsf_graphql_image_fields lmsf_after_product_imported
Custom metafields lmsf_graphql_product_extra_fields lmsf_after_product_imported
Tag mapping lmsf_graphql_product_extra_fields lmsf_after_product_imported
Scheduled sync lmsf_sync_extra_product_fields lmsf_sync_product_extra
The license stub pattern
The Pro build includes a license validation system. The free build needs
a license.php file too — but without any external calls or validation
logic.

I maintain two files:

includes/license.php — full Pro license validation (LM4WC calls)
includes/license-stub.php — stub that returns safe defaults
// license-stub.php — ships in the free build
function lmsf_get_license_tier(): string  { return 'free'; }
function lmsf_get_license_key(): string   { return ''; }
function lmsf_is_license_valid(): bool    { return false; }
function lmsf_upgrade_url(): string       {
    return 'https://www.laterretagames.com/migrate-from-shopify-to-woocommerce/';
}
The build script swaps them:

if $FREE_BUILD; then
    cp "$LICENSE_STUB" "$STAGE_DIR/includes/license.php"
else
    cp "$LICENSE_FILE" "$STAGE_DIR/includes/license.php"
fi

Same function signatures, different implementations. The main plugin
calls lmsf_upgrade_url() to render the "Get Pro" button — it works in
both builds without any conditional.

What this architecture can't do
Discovery is harder. A user on the free build can't see a list of
Pro features inside the plugin unless you explicitly build a "What's in
Pro" section. The features are absent, not locked — so there's nothing
to surface automatically.

Solution: Build static Pro feature cards into the free dashboard.
Show exactly what the migration didn't do because Pro wasn't active.

// Free dashboard — always visible
if ( defined( 'LMSF_FREE_VERSION' ) && LMSF_FREE_VERSION ) {
    // Show cards: images not downloaded, sync not active, tags not mapped
}

Deactivation hooks need a constant. register_deactivation_hook()
requires the main plugin file path. If Pro files reference it, they need
a constant defined in the main plugin:

// Main plugin
define( 'LMSF_FILE', __FILE__ );

// Pro: scheduler.php
register_deactivation_hook( LMSF_FILE, 'lmsf_clear_cron_schedule' );

Is it worth the complexity?
Yes — for three reasons:

WP.org compliance is non-negotiable. Getting suspended means
losing organic discovery permanently. The hook architecture is
the only clean way to stay compliant.
The architecture is actually better code. Hooks as extension
points is how WordPress itself is designed. Pro features are properly
isolated — a bug in images.php can't affect the migration core.
It scales. Every new Pro feature is a new file in includes/pro/.
No changes to the main plugin required beyond adding an extension point.
The free plugin on WP.org:
👉 Laterreta Migrator for Shopify

If you're building a freemium WP plugin and have questions about the
compliance side, happy to go into more detail in the comments.