Database Schema

LicenceForge creates eight custom tables in your WordPress database, all prefixed with wplf_ (after the standard WordPress table prefix). This page documents every column, index, and foreign-key relationship.

Entity relationships

The diagram below describes how the eight tables relate to one another. Primary keys are marked PK and foreign keys are marked FK.

wplf_products (PK: id)
  |
  |--< wplf_product_prices (FK: product_id -> products.id, ON DELETE CASCADE)
  |
  |--< wplf_licenses (FK: product_id -> products.id, ON DELETE RESTRICT)
  |       |
  |       |--< wplf_activations (FK: license_id -> licenses.id, ON DELETE CASCADE)
  |       |
  |       |--< wplf_audit_log (FK: license_id -> licenses.id, ON DELETE SET NULL)
  |       |
  |       |--< wplf_analytics (license_id -- no FK constraint)
  |
  |--< wplf_api_keys (product_id -- no FK constraint, nullable)

wplf_licenses
  |--< FK: price_id -> wplf_product_prices.id (ON DELETE SET NULL)

wplf_webhook_events (standalone, no foreign keys)

wplf_products

Stores every product (plugin or theme) managed by LicenceForge. Each product has a unique slug used throughout the REST API and client library.

wplf_product_prices

Defines the pricing tiers available for each product. Each tier maps to a Stripe Price or WooCommerce Product and controls activation limits and feature gating.

wplf_licenses

The core licence table. Each row represents a single licence key issued to a customer, linked to a product and optionally to a pricing tier, user, and payment source.

Indexes

wplf_activations

Tracks every site that has activated a licence. A licence can have multiple activation rows up to its activation_limit. Deactivated sites retain their row with a non-null deactivated_at timestamp.

Indexes

wplf_webhook_events

Stores every inbound webhook event from Stripe (and potentially other sources). Used for idempotent processing, retry logic, and debugging failed deliveries.

Indexes

wplf_audit_log

Immutable audit trail of every significant action: validation attempts, activations, deactivations, key rotations, and admin operations. Used for security analysis and compliance.

Indexes

wplf_analytics

General-purpose event tracking for licence and site activity. Powers the analytics dashboard with activation trends, version distribution, and usage patterns.

wplf_api_keys

Stores hashed API keys used for authenticating external integrations against the admin REST endpoints. Keys are scoped by permission level and optionally restricted to a single product.

SQL creation reference

The following is a simplified representation of the CREATE TABLE statements. The actual statements use $wpdb->prefix and are generated by the installer class.

CREATE TABLE wplf_products (
    id              bigint unsigned NOT NULL AUTO_INCREMENT,
    slug            varchar(100)    NOT NULL,
    name            varchar(255)    NOT NULL,
    description     text,
    homepage_url    varchar(255),
    latest_version  varchar(20)     DEFAULT '1.0.0',
    zip_path        varchar(500),
    zip_hash        varchar(64),
    external_url    varchar(500),
    requires_wp     varchar(10)     DEFAULT '5.8',
    tested_wp       varchar(10)     DEFAULT '6.4',
    requires_php    varchar(10)     DEFAULT '7.4',
    changelog       longtext,
    is_active       tinyint(1)      DEFAULT 1,
    trial_enabled   tinyint(1)      DEFAULT 0,
    trial_days      int             DEFAULT 14,
    rollout_percentage int          DEFAULT 100,
    rollout_version varchar(20),
    rollout_pulled  tinyint(1)      DEFAULT 0,
    require_fingerprint tinyint(1)  DEFAULT 0,
    fingerprint_mismatch_action varchar(10) DEFAULT 'warn',
    created_at      datetime,
    updated_at      datetime,
    PRIMARY KEY (id),
    UNIQUE KEY slug (slug)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_product_prices (
    id              bigint unsigned NOT NULL AUTO_INCREMENT,
    product_id      bigint unsigned NOT NULL,
    label           varchar(100),
    stripe_price_id varchar(100),
    wc_product_id   bigint unsigned,
    price_interval  enum('month','year','lifetime') NOT NULL,
    price_amount    decimal(10,2)   NOT NULL,
    activation_limit int            NOT NULL,
    features        text,
    is_active       tinyint(1)      DEFAULT 1,
    created_at      datetime,
    PRIMARY KEY (id),
    FOREIGN KEY (product_id) REFERENCES wplf_products(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_licenses (
    id                      bigint unsigned NOT NULL AUTO_INCREMENT,
    product_id              bigint unsigned NOT NULL,
    price_id                bigint unsigned,
    user_id                 bigint unsigned,
    order_id                bigint unsigned,
    stripe_subscription_id  varchar(100),
    wc_subscription_id      bigint unsigned,
    license_key_hash        varchar(64)     NOT NULL,
    status                  varchar(20)     NOT NULL DEFAULT 'active',
    activation_limit        int             NOT NULL DEFAULT 1,
    current_period_end      datetime,
    customer_email          varchar(255),
    customer_name           varchar(255),
    created_at              datetime,
    updated_at              datetime,
    PRIMARY KEY (id),
    UNIQUE KEY license_key_hash (license_key_hash),
    KEY idx_licenses_created (created_at),
    KEY idx_licenses_email (customer_email),
    FOREIGN KEY (product_id) REFERENCES wplf_products(id)        ON DELETE RESTRICT,
    FOREIGN KEY (price_id)   REFERENCES wplf_product_prices(id)  ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_activations (
    id                 bigint unsigned NOT NULL AUTO_INCREMENT,
    license_id         bigint unsigned NOT NULL,
    site_origin        varchar(255)    NOT NULL,
    user_agent         text,
    server_fingerprint varchar(64),
    activated_at       datetime        NOT NULL,
    last_seen_at       datetime,
    deactivated_at     datetime,
    PRIMARY KEY (id),
    KEY idx_activations_last_seen (last_seen_at),
    FOREIGN KEY (license_id) REFERENCES wplf_licenses(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_webhook_events (
    id               bigint unsigned NOT NULL AUTO_INCREMENT,
    event_id         varchar(255)    NOT NULL,
    event_type       varchar(100)    NOT NULL,
    source           varchar(20)     NOT NULL,
    processed_at     datetime,
    processing_error text,
    retry_count      smallint        DEFAULT 0,
    next_retry_at    datetime,
    payload          longtext,
    created_at       datetime        NOT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY event_id (event_id),
    KEY idx_webhook_source (source),
    KEY idx_webhook_retry (next_retry_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_audit_log (
    id               bigint unsigned NOT NULL AUTO_INCREMENT,
    action           varchar(100)    NOT NULL,
    product_slug     varchar(100),
    license_id       bigint unsigned,
    site_origin_hint varchar(255),
    outcome          varchar(20),
    ip_hash          varchar(16),
    metadata         text,
    created_at       datetime        NOT NULL,
    PRIMARY KEY (id),
    KEY idx_audit_outcome (outcome),
    FOREIGN KEY (license_id) REFERENCES wplf_licenses(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_analytics (
    id           bigint unsigned NOT NULL AUTO_INCREMENT,
    license_id   bigint unsigned,
    site_origin  varchar(255),
    event_type   varchar(50)     NOT NULL,
    event_data   text,
    recorded_at  datetime        NOT NULL,
    PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wplf_api_keys (
    id             bigint unsigned NOT NULL AUTO_INCREMENT,
    api_key_hash   varchar(64)     NOT NULL,
    api_key_prefix varchar(8)      NOT NULL,
    label          varchar(255)    NOT NULL,
    product_id     bigint unsigned,
    permissions    varchar(20)     NOT NULL DEFAULT 'read',
    last_used_at   datetime,
    is_active      tinyint(1)      DEFAULT 1,
    created_at     datetime        NOT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY api_key_hash (api_key_hash)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Related pages

• Hooks Reference -- Hook data often maps directly to these table columns
• REST API Reference -- API responses reflect this schema
• Extending LicenceForge -- Build custom integrations on top of the schema
• Encryption & Security -- How licence keys and API keys are hashed