License Lifecycle

Every license in LicenceForge follows a defined state machine. Understanding the available states and the valid transitions between them is essential for managing licenses effectively and building integrations that respond correctly to status changes.

License states

A license can be in one of five states at any given time:

State Badge Description
Active Active The license is valid and can be used to activate sites. This is the standard operational state for paid licenses.
Trial Trial The license is in a time-limited trial period. Trial licenses function identically to active licenses but are tracked separately for reporting and enforcement. Trial duration is configured per product.
Expired Expired The license has passed its expiration date. Expired licenses no longer validate successfully (subject to the grace period). They can be reactivated by extending the expiration date.
Suspended Suspended The license has been temporarily disabled by an administrator. Suspended licenses do not validate. This state is typically used for payment disputes or policy violations.
Cancelled Cancelled The license has been permanently revoked. This is a terminal state—cancelled licenses cannot be transitioned to any other state. A new license must be created if the customer needs access again.

State transitions

Not all transitions between states are permitted. The following table defines every valid transition in the system:

From state Allowed transitions
Active Expired, Cancelled, Suspended
Trial Active, Expired, Cancelled, Suspended
Expired Active, Cancelled
Cancelled None (terminal state)
Suspended Active, Cancelled

Attempting an invalid transition (for example, moving a cancelled license to active) will return a WP_Error with the code wplf_invalid_transition.

Transition diagram

The following diagram illustrates the complete state machine. Arrows indicate the direction of valid transitions:

                  +--------+
                  | Trial  |
                  +--------+
                 /  |   |   \
                v   |   |    v
         +--------+ |   | +----------+
         | Active | |   | | Expired  |
         +--------+ |   | +----------+
          |   |  \  |   |   |    |
          |   |   v v   v   v    |
          |   | +-----------+    |
          |   | | Suspended |    |
          |   | +-----------+    |
          |   |      |          |
          v   v      v          v
         +---------------------------+
         |        Cancelled          |
         +---------------------------+

Automatic transitions

Two transitions happen automatically without administrator intervention:

  • Active/Trial to Expired — The wplf_check_expirations cron job runs daily and transitions any license whose expires_at date has passed.
  • Trial to Active — When a trial license receives a qualifying payment (through WooCommerce or Stripe), it is automatically promoted to active status with the new expiration date from the subscription.

Grace period

When a license expires, it does not immediately fail validation. LicenceForge provides a configurable grace period during which expired licenses continue to validate successfully. This allows customers a window to renew before their software stops functioning.

The grace period is controlled by the wplf_grace_period_days option:

Option Type Default Description
wplf_grace_period_days Integer 3 Number of days after expiration during which the license still validates. Set to 0 to disable the grace period entirely.

During the grace period, the validation API response includes a grace_period flag set to true and a grace_expires_at timestamp. Client integrations can use this information to display a renewal notice to the end user:

{
  "valid": true,
  "status": "expired",
  "grace_period": true,
  "grace_expires_at": "2026-03-05T00:00:00Z",
  "message": "License expired. Grace period ends in 2 days."
}

Note

The grace period applies only to the Expired state. Suspended and cancelled licenses never validate, regardless of the grace period setting.

Auto-deactivation

When a license transitions to an expired or cancelled state, LicenceForge can optionally deactivate all associated site activations automatically. This behaviour is controlled by the wplf_auto_deactivate option:

Option Type Default Description
wplf_auto_deactivate Boolean true When enabled, all active site activations are deactivated when the license transitions to expired or cancelled.

When auto-deactivation triggers, the following occurs:

  1. All rows in wplf_activations for the license that have a NULL deactivated_at value are updated with the current timestamp.
  2. The wplf_activation_deactivated action hook fires once per deactivated site, passing the activation ID and license ID.
  3. If the grace period has not yet elapsed (for expired licenses), deactivation is deferred until the grace period ends.

Important

Auto-deactivation is not reversible. If a license is later reactivated (e.g., an expired license is renewed), the customer must re-activate their sites manually. Previous activations are not automatically restored.

Hooks

LicenceForge fires action hooks on every state transition, allowing developers to extend behaviour:

// Fires on every status change
do_action( 'wplf_license_status_changed', $license_id, $new_status, $old_status );

// Fires for specific transitions
do_action( "wplf_license_{$old_status}_to_{$new_status}", $license_id );

// Examples:
// wplf_license_active_to_expired
// wplf_license_trial_to_active
// wplf_license_suspended_to_cancelled

See the Hooks Reference for a complete list of available action and filter hooks.