ITX HostKit

1. Introduction

1.1 What is ITX HostKit?

ITX HostKit is a WordPress plugin that turns any WordPress + WooCommerce site into a fully automated WHM/cPanel hosting business. It connects your WHM servers to WooCommerce so customers can buy hosting plans, get cPanel accounts provisioned automatically on payment, manage their subscriptions from My Account, and receive invoices and renewal reminders — all without leaving WordPress.

1.2 Key Features at a Glance

1.3 System Requirements

2. Installation & Setup

2.1 Installing the Plugin

1. Make sure WooCommerce is installed and active.
2. In WordPress admin go to Plugins → Add New → Upload Plugin and upload itx-hostkit.zip.
3. Click Install Now and then Activate Plugin.
4. Visit Settings → Permalinks and click Save Changes once to flush rewrite rules.
5. The plugin will redirect you to the Setup Wizard automatically the first time you visit any HostKit page.

2.2 What Happens on Activation

The activator performs the following on first activation and on every version upgrade:

• Creates all custom database tables.
• Generates an AES-256 encryption key and stores it as a WordPress option (used to encrypt WHM API tokens).
• Creates the secure invoice storage directory under wp-content/uploads/hk-invoices/ with a hardened .htaccess.
• Auto-configures WooCommerce Cart and Checkout pages with the [woocommerce_cart] and [woocommerce_checkout] shortcodes if missing.
• Schedules WP-Cron jobs for daily renewal checks, hourly provisioning queue checks, and other recurring work.
• Seeds the four built-in HostKit roles (HK Admin, Billing Manager, Support Agent, Reseller).
• Registers custom URL rewrites and My Account endpoints.

2.3 Setup Wizard

The Setup Wizard at admin.php?page=hk-setup-wizard walks you through initial configuration in seven steps:

You can re-run the wizard at any time from Settings → Run Setup Wizard.

2.4 Activation Checklist

1. WooCommerce installed and active.
2. WHM API token generated (Home → Development → Manage API Tokens in WHM).
3. WordPress site URL reachable on HTTPS.
4. Setup Wizard completed (server added, at least one product mapped to a WHM package).
5. Test order placed and processed end-to-end — cPanel account created and welcome email received.

3. Admin Dashboard

HostKit uses a custom two-level horizontal navigation that replaces the default WordPress submenu. The top row is the section tabs; the row below is the page tabs for the active section. This keeps the wp-admin sidebar from getting crowded once you have many pages.

3.1 Navigation Structure

3.2 Dashboard Page

The Dashboard at admin.php?page=hk-dashboard is your operational overview. It shows:

• KPI tiles — total active hostings, monthly recurring revenue (MRR), unpaid invoices, overdue accounts.
• Server status grid — live load averages and disk usage for each connected WHM server.
• Recent activity — the last 20 audit-log events.
• Pending alerts — failed provisioning attempts, queued plan changes, expiring trials.
• Quick links — jump to the Setup Wizard or Add New Hosting.

3.3 In-Page Conventions

Every list page (Hostings, Servers, Products, Invoices, etc.) follows the same conventions:

• Breadcrumbs at the top (HostKit → Section → Page).
• Filters and search in a horizontal toolbar — filters update the URL so you can bookmark a filtered view.
• Bulk actions dropdown above the table.
• Toast notifications for success/error feedback.
• Confirmation modals for destructive actions (cancel, terminate, delete).

3.4 Theming

The admin theme palette is configurable from Settings → UI & Display. Two design-token families control the look: a brand palette for primary and accent colours, and a UI palette for surface, text, border, success, danger, and so on. Changing the brand colour automatically retheme every page.

4. WHM/cPanel Server Management

4.1 Adding a Server

Go to Hosting → Servers → Add New Server. You will need:

4.2 Test Connection

Every server card has a Test Connection button. Clicking it calls the WHM API version endpoint and reports back the WHM version, the available account count, and any error messages. Use this whenever you change a token or after a server move.

4.3 Server Health Monitoring

The plugin polls each server periodically and surfaces:

• Load averages (1, 5, 15 minute).
• Disk usage per partition.
• Account count vs. limit.
• Last reachable timestamp — if the API has not responded for the configured threshold, the server is marked offline and excluded from automatic provisioning.

4.4 Server Detail Page

Click any server name to open its detail page. From there you can:

• View all hosting accounts on that server with status and renewal date.
• Run reconciliation between WHM-side state and plugin-side state.
• Trigger a manual health check.
• Suspend or unsuspend the server itself (so no new accounts will be assigned to it while you do maintenance).

5. Package Management

Packages are the resource-limit definitions you sell to customers. They mirror WHM packages 1:1 but are stored locally so the admin doesn't have to round-trip to WHM every time the catalogue is rendered.

5.1 Resource Limits

5.2 Sync from WHM

The Packages page has a Sync from WHM button that pulls all packages from the selected server and creates or updates the corresponding local package rows. Use it after creating or editing packages directly in WHM.

5.3 Editing Packages

Edit a package locally in HostKit and the change is pushed back to WHM via the editpkg API call. The package name is immutable once created.

6. Products & Plan Mapping

6.1 Hosting Product Type

The plugin registers a custom WooCommerce product type called hosting_product. Use this product type for any item you want to sell as a hosting plan.

6.2 Creating a Hosting Product

1. Go to Sales & Billing → Products → Add New Product.
2. Set product type to Hosting Product.
3. Fill in the standard WooCommerce fields (name, description, gallery, SEO).
4. In the HostKit panel set the prices for each billing cycle you want to offer (monthly, quarterly, semi-annual, yearly, biennial, triennial).
5. Configure trial settings if applicable: trial duration, repeat-trial prevention, and proration behaviour.
6. Save the product, then click Map to WHM Package.

6.3 Plan Mapping

A mapping links a product on a specific server to a WHM package. A product can be mapped to multiple servers; when a customer orders, the load balancer picks the server with the most headroom.

6.4 Same-Server Plan Mapping

When a product is mapped to multiple servers and a customer changes their plan, the plugin prefers the customer's current server when picking the target mapping — preventing the account from being moved to a different server unnecessarily.

6.5 Pricing Configuration

Each cycle stores its own price in product meta. The pricing-table shortcode reads two specific meta keys for split monthly/yearly display:

• _hk_price_monthly
• _hk_price_yearly

If those are missing the table falls back to the standard product price.

7. Domain Validation

Domain Validation refers to validating the domain name a customer types at checkout for their hosting account — format checks, reserved-word checks, duplicate detection, and an optional DNS lookup.

7.1 Checkout-Time Checks

When a customer adds a hosting product to the cart they are prompted for a domain name. Before the order goes through, the plugin runs a configurable chain of checks:

• Format check — confirms the string is a syntactically valid domain.
• Reserved-word check — rejects forbidden words and patterns (configurable list).
• Duplicate check — ensures no other active subscription already has this domain on any of your WHM servers.
• DNS check (optional) — resolves the domain and warns if it currently points elsewhere, so the customer knows DNS needs to be updated.

7.2 Configuration

All checks are configured in Settings → Domain Validation. You can toggle each check on or off and customize the error message shown to the customer. The reserved-word list and the DNS-check timeout are both editable.

8. Order Management

8.1 Orders List

The Orders page at Sales & Billing → Orders shows every WooCommerce order that contains a hosting product. You can filter by status, by customer, by product, or by date range, and search by order ID, customer email, or domain.

8.2 Single-Order Page

Each order's detail page consolidates everything related to that order:

• Order header with WooCommerce status, customer, total, payment method, and date.
• Linked subscription with one-click jump to the hosting detail page.
• Linked invoice with type label (paid, unpaid, proforma, credit note, cancelled), download PDF, and Resend to Customer.
• Generate Invoice button when the order has no invoice yet.
• Mark as Paid button for offline payments — uses WooCommerce's native payment-complete flow internally so the paid date is recorded and downstream hooks fire.
• Send Payment Reminder — context-aware: picks the right email template based on the subscription state. 60-second rate limit per subscription.
• Order activity — the same audit-log timeline that appears on the subscription page.

8.3 Mark as Paid (Offline Payment)

The unified Mark-as-Paid flow goes through WooCommerce's native payment-complete handler instead of a bare status flip. Practical effects:

• The paid date is recorded, so WooCommerce reports show accurate revenue dates.
• The standard woocommerce_payment_complete hook fires, so other extensions that listen for it (analytics, accounting, etc.) work as expected.
• Offline payments are tagged with a meta flag for downstream reporting.

9. Hosting Account Provisioning

9.1 The Provisioning Flow

When a customer's order completes, the plugin runs this sequence:

9.2 Failure Handling — Provision Queue

If the WHM createacct call fails for a transient reason (network error, WHM busy, timeout), the subscription is marked failed and a row is added to the provisioning retry queue. An hourly cron picks up due rows and re-attempts up to a configurable maximum on a configurable backoff schedule.

9.3 Manual Provisioning

From the single hosting page you can:

• Retry provisioning — re-runs createacct if the previous attempt failed.
• Link existing account — if the cPanel account was created outside the plugin, you can link it back so renewals and emails work.
• Recreate account on a different server — use this if you want to migrate an account.

10. Hostings

10.1 Lifecycle States

10.2 Single-Hosting Page

The single hosting detail page is the central control panel for one customer's account. Major sections:

• Account details — domain, cPanel username, server, package, billing cycle, renewal date.
• Status panel with action buttons: Suspend, Reactivate, Cancel, Terminate, Hold, Resume.
• Login as Customer button — opens an impersonation session.
• cPanel direct login — one-click WHM "Create User Session" link, no password needed.
• Send Payment Reminder — context-aware email send.
• Invoice section — all invoices for this subscription with type labels and download links.
• Renewal history — every past order linked to this subscription.
• Plan change — request an upgrade or downgrade (lands in the review queue).
• Activity timeline — unified feed of emails, internal notes, and audit-log events.

10.3 Trials

When a product has a trial configured, new subscriptions start in trial mode. The system:

• Sends a trial-started email immediately.
• Sends a trial-ending-soon email N days before the trial ends, via a daily cron. N is configurable (default 3).
• Marks the reminder as sent to prevent duplicate dispatches.
• Optionally prevents repeat trials per customer (configurable per product).

10.4 Holiday Hold

Customers can put a subscription on Hold from My Account. The account is suspended on WHM, the renewal cron is paused, and an admin notification fires. Resume restores the account and resumes billing from the new date.

10.5 Add Existing Subscription

The Add Existing Subscription flow lets you import an account that already exists on your WHM server — useful when you migrate from another billing system. It links the existing cPanel account to a WordPress user without creating a new one.

11. Plan Change Review Queue

11.1 How It Works

Admin-initiated plan changes land in a review queue at Hosting → Plan Changes instead of being applied instantly. Customer-initiated flows are different: customer downgrades auto-schedule for the next renewal, and customer upgrades auto-charge with proration.

11.2 Per-Row Actions

Every queued row has three actions:

11.3 Status Values

The plan-change status values are: pending, approved, processing, completed, cancelled.

11.4 Proration & Credit Notes

Upgrades charge a prorated amount for the unused remainder of the current cycle. Downgrades issue a credit note for the unused balance:

• The proration calculator computes the prorated amount.
• The plan-transition handler applies the change and, on downgrade, generates a credit note after the WooCommerce refund succeeds.
• The credit note PDF is linked to the original paid invoice.

Credit-note generation is controlled by the Generate credit notes setting (default: on).

11.5 Invoice Regeneration

When a plan change applies, the old unpaid or proforma invoice for the original order is converted to the cancelled invoice type and a fresh invoice is generated for the replacement order. This keeps the audit trail clean and prevents customers paying an invoice that no longer reflects their real plan.

11.6 Daily Worker

A daily cron picks up admin-scheduled rows whose effective date is today and applies them. Failures are logged to the audit log and the row stays in processing until the next run.

12. Billing & Invoicing

12.1 Invoice Types

12.2 PDF Generation

PDFs are generated by a self-hosted PDF library and saved to wp-content/uploads/hk-invoices/. The directory has a hardened .htaccess that blocks direct file access; downloads are served through a secure endpoint that checks the requesting user's permission.

12.3 Invoice Numbering

Invoice numbers use a configurable prefix and zero-padded sequence: {prefix}-{YEAR}-{0001}. Configure in Settings → Invoices. The sequence is locked at the database level to prevent duplicates under concurrent requests.

12.4 Invoice PDF Attachment

The invoice PDF is attached to all subscription emails — renewal reminders, subscription created, suspended notices, payment confirmations, and any manual Resend to Customer.

12.5 Generate Invoice Button

If an order somehow has no invoice (e.g., it was created manually), the order detail page shows a Generate Invoice button that creates one on demand.

12.6 Resend to Customer

The Resend to Customer button on the invoice and order pages re-emails the invoice to the billing email with the PDF attached. The Resend button is hidden for credit notes (since credit notes are auto-generated and rarely need to be resent).

13. Subscription Renewal System

13.1 Automatic Renewal Order Creation

A daily cron creates renewal orders for any subscription whose next-payment date falls within the configured lead time. The lead time is configurable in Settings → Hostings; default is 7 days.

13.2 Off-Session Auto-Charge

If the customer has a saved payment method on their subscription, the plugin attempts an off-session charge against the saved card via the WooCommerce gateway. Success completes the order, sends the payment confirmation email with attached PDF, and updates the last-payment and next-payment dates.

13.3 Renewal Reminder Emails

Reminder emails fire at configurable intervals before the renewal date. Default schedule: 29, 15, 7, 1 days before. Configure in Settings → Emails → Reminder schedule.

13.4 Manual Send Payment Reminder

The Send Payment Reminder button picks the right template based on subscription state:

Manual sends bypass the email-notification kill switch, but are still subject to the 60-second per-subscription rate limit.

14. Dunning & Failed Payments

14.1 The Dunning Queue

When a renewal payment fails, the subscription is moved to failed status and an entry is added to the dunning queue for retry. The cron worker re-attempts the charge on the configured backoff schedule and progressively escalates communications:

14.2 Configurable Settings

All thresholds live under Settings → Hostings:

• Number of retry attempts before suspension.
• Retry interval (in days) between attempts.
• Grace period (in days) after suspension before automatic termination.
• Whether to auto-terminate or require admin confirmation.

14.3 Overdue Aging Reports

The Analytics page includes an Overdue Aging report bucketing unpaid invoices into 0–30, 31–60, 61–90, and 90+ days. Useful for picking out long-tail unpaid invoices that need a personal follow-up.

15. Reconciliation

15.1 Why It Exists

WHM and the plugin can drift out of sync if a cPanel account is suspended, terminated, or created directly on WHM, or if a network blip makes a WHM API call appear to fail when it actually succeeded. The Reconciliation page at Sales & Billing → Reconciliation compares the two views and surfaces every mismatch.

15.2 Mismatch Types

15.3 Sync Actions

Each mismatch row has two buttons:

• Sync → WHM — pushes the plugin's state to WHM (e.g., suspends the account on WHM if the plugin says suspended).
• Sync → Plugin — pulls WHM's state into the plugin (e.g., marks the subscription suspended if WHM has it suspended).

16. Coupons

16.1 HostKit Coupons

HostKit ships its own coupon system, separate from WooCommerce coupons because the plugin needs first-class control over per-user limits, renewal reapplication, and product-cycle scoping.

16.2 Coupon Configuration

16.3 Where Coupons Apply

Customers enter coupons at checkout. If valid, the discount is shown in the cart, applied to the order, and (if renewal reapplication is enabled) stored on the subscription so future renewal orders inherit the same discount.

17. Load Balancing

17.1 Server Picker

When a hosting product is mapped to multiple servers, the load balancer picks the server with the most available capacity at provision time. The picker takes into account:

• Server availability (online and last health check OK).
• Account count vs. configured limit.
• Current load average and disk utilization.
• Whether the server is paused for maintenance.

17.2 Sticky Server on Plan Changes

When an existing customer changes plans, the picker prefers the customer's current server — only falling back to the load balancer if the current server doesn't have a mapping for the target product. This avoids unnecessary cross-server moves on simple upgrades.

17.3 Failover

If a server's health check fails repeatedly it is automatically excluded from the load balancer pool. New provisioning attempts go to the next-best server. Existing accounts on the failing server are not migrated automatically — you'll see them on the Reconciliation page.

18. Email Notification System

18.1 How It Works

Each email event has its own template (subject and body). Templates are editable from Settings → Emails. If an event has no custom template, the system falls back to the built-in default. Each template can use placeholder tokens that are replaced at send time with subscription and customer data.

18.2 Customer Email Events

The plugin currently dispatches 24+ event types. The most common:

18.3 Placeholder Tokens

Templates support {token} substitution. Universal placeholders available in every event:

{site_name}            {customer_name}        {customer_email}
{domain}               {product_name}         {billing_cycle}
{next_payment_date}    {amount}               {status}
{subscription_id}      {portal_url}           {support_email}

Trial events additionally have {trial_end_date} and {trial_days_remaining}. The hold event has {billing_note}.

18.4 Editing Templates

Go to Settings → Emails. Each event has a collapsible accordion containing a subject text field, a TinyMCE body editor, a placeholder reference table, and a Reset to Default button. Save Changes writes your overrides; Reset reverts to the plugin defaults.

18.5 Admin Notifications

Internal admin notifications fire independently of customer emails. Configure which events the admin gets copies of in Settings → Emails. The four currently supported are:

• Subscription activated
• Subscription cancelled
• Subscription hold
• Renewal payment failed

Selected events are emailed to the WordPress admin email. Admin notifications are internal copies only — they're not logged to the per-subscription timeline.

18.6 Email Kill Switch

The Disable email notifications toggle in Settings is a master kill switch. Manual sends from action buttons (Send Payment Reminder, Resend to Customer) bypass the kill switch so admins can still communicate with customers when needed.

18.7 Weekly Business Report

An optional weekly digest emails the admin a summary of MRR, ARR, new sign-ups, churn, overdue invoices, and trial conversions. Configure delivery day, time, and recipient list in Settings.

19. Customer Portal (My Account)

19.1 What Customers See

The plugin extends WooCommerce's My Account with hosting-specific endpoints. The new tabs:

• Hosting Dashboard — subscription overview, alerts, quick links.
• Hostings — list of all subscriptions with status pills, renewal dates, and quick actions.
• Subscription Detail — full account info, cPanel login button, plan change request, hold/resume, billing history.
• Invoices — covered in the next section.
• Two-Factor Authentication — TOTP setup and backup codes.

19.2 Customer Actions

From the portal a customer can:

• Pay an unpaid invoice via WooCommerce's standard checkout.
• Request a plan change — downgrades auto-schedule, upgrades go through proration.
• Pause (hold) and resume a subscription.
• Cancel a subscription (configurable: immediate vs end-of-term).
• Access cPanel via one-click WHM session login.
• Download invoice and credit-note PDFs.
• Set up two-factor authentication.
• Apply a coupon to a renewal (if renewal reapplication is allowed).

19.3 Styling

Portal pages share the same brand colour palette as the admin so a single colour-scheme change retheme everything.

20. Customer Invoices Tab

20.1 Overview

The Invoices tab on My Account at /my-account/hk-invoices/ shows all of a customer's invoices across all subscriptions in one place, with type badges and PDF downloads.

20.2 Filters & Search

• Filter by type — Paid, Unpaid, Credit Note, Cancelled.
• Search by domain or invoice number.
• Pagination for customers with long histories.

20.3 Per-Row Actions

20.4 Reseller Multi-Tenancy

Resellers see the invoices for their own subscriptions plus those of any customers assigned to them. An All Owners dropdown filter lets them narrow the list to a specific customer. Regular customers don't see the filter.

21. Reseller Portal

21.1 What Resellers See

A user with the Reseller role gets a multi-tenant view: their own subscriptions plus those of customers assigned to them. Each row carries an Owner: {customer name} subtitle so resellers can quickly tell their own subscriptions from their assigned customers'.

21.2 Owner Filter

An All Owners dropdown filter appears on hosting and invoice lists for resellers (and is hidden for regular customers). Useful when a reseller manages many customers and wants to focus on one at a time.

21.3 Customer Assignment

Admins assign customers to a reseller from the Resellers page or by editing an individual user's profile. A customer can be assigned to at most one reseller. The reseller can then see and act on that customer's hostings.

22. Login as Customer (Impersonation)

22.1 What It Does

The Login as Customer button appears on the single hosting detail page and the Users list (admin only). One click logs you into WordPress as that customer so you can see the My Account portal exactly as they see it — useful for support and reproducing user-reported issues.

22.2 How It Works

The session is switched at the auth-cookie level. Before switching, the plugin sets a separate signed cookie containing the original administrator's user ID, using HMAC-SHA256 with the WordPress auth salt. The impersonator cookie expires after 2 hours.

22.3 Visual Indicators

• A persistent banner at the top of every page during the session: "You are impersonating {customer name}. Return to admin."
• A pill in the WordPress admin bar showing the same status.
• Both clickable to end the session and return to the original admin user.

22.4 Security

• Every switch-to and switch-back event is written to the audit log.
• Nested impersonation is blocked — you can't impersonate while you're already impersonating someone else.
• Impersonating other administrators is blocked — you can only impersonate non-admin users.
• The cookie auto-expires after 2 hours so a forgotten session doesn't stay open indefinitely.
• Capability gate: hk_impersonate_customers (granular, configurable per role).

23. Two-Factor Authentication

23.1 TOTP-Based 2FA

HostKit ships an RFC 6238 TOTP implementation. It works with any standard authenticator app (Google Authenticator, Authy, 1Password, Bitwarden, etc.).

23.2 Customer Enrollment

From My Account, a customer:

1. Clicks Enable Two-Factor Authentication.
2. Scans the displayed QR code with their authenticator app.
3. Enters the current 6-digit code to confirm setup.
4. Receives a set of one-time backup codes to print and store securely.

23.3 Storage

The TOTP secret is base32-encoded (160-bit), encrypted with the same AES-256 key used for WHM tokens, and stored in user meta. Backup codes are stored hashed.

23.4 Login Flow

When 2FA is enabled, after a successful password login the customer is shown a code-entry screen. The plugin verifies the entered code against the current TOTP and the previous and next 30-second windows (to absorb clock drift). After 5 consecutive failed attempts, the account is throttled for 15 minutes.

23.5 Recovery

Backup codes are single-use. Each successful backup-code login marks that code consumed. If the customer loses both their authenticator and their backup codes, an admin can reset 2FA from the user detail page; the action is audit-logged.

24. Users & Customers

24.1 Users List

The Users page at Users & Access → Users shows every customer that has at least one HostKit subscription, plus any user with a HostKit role. Per-row data: name, email, subscription count, total spend, last login.

24.2 Single User Page

The user detail page consolidates everything about one customer:

• Profile fields (synced with WP user meta).
• All hostings (subscriptions) belonging to this user.
• All invoices.
• Per-user analytics (CLV, total revenue, average revenue per cycle).
• Audit log entries filtered to this user.
• Assigned reseller (for reseller-managed customers).
• Assigned HostKit roles with add/remove controls.
• Two-factor status (enabled/disabled, with reset action).
• Login as Customer button.

24.3 Add New User

The Add New User form lets you create a customer record without going through WooCommerce checkout — useful for pre-creating accounts before a manual subscription assignment.

25. Roles & Permissions

25.1 Why HostKit Has Its Own Role System

WordPress's built-in roles are too coarse for a hosting platform. HostKit ships its own role and capability system that runs alongside WordPress roles — users can have one or more HostKit roles in addition to their WordPress role.

25.2 The 31 Capabilities

25.3 Built-in Roles

25.4 Custom Roles

Create unlimited custom roles at Users & Access → Roles & Permissions → Add New Role. Each role has a unique key (immutable once saved), display name, description, and a checkbox grid for the 31 capabilities.

25.5 Multi-Role Assignment

A user can have multiple HostKit roles simultaneously. The effective capability set is the union of all assigned roles. Assign or remove roles from the user detail page.

25.6 Use the Helper

For developers extending the plugin, always use the hk_current_user_can() helper instead of current_user_can('manage_options') when gating HostKit features. WP admins short-circuit immediately; non-admins are checked against the HostKit role/capability mapping.

if ( ! hk_current_user_can( 'hk_manage_invoices' ) ) {
    wp_die( __( 'You do not have permission.', 'itx-hostkit' ) );
}

26. Audit Log

26.1 What's Logged

The audit log records every meaningful action taken by an admin or by the system. Examples:

• Subscription state changes (activated, suspended, cancelled, terminated, hold/resume).
• Plan changes (requested, scheduled, applied, cancelled).
• Server add/edit/delete.
• Login as Customer (switch-to and switch-back).
• Settings saves.
• Role and capability changes.
• Manual invoice generation, mark-as-paid, resend.
• Reconciliation sync actions.
• Failed permission checks (potential abuse signals).

26.2 Filtering

The Audit Log page at Insights → Audit Log supports filtering by event type, user, subscription, server, and date range. The same data also feeds the per-subscription activity timeline on the single hosting page.

26.3 Retention

Audit log retention is configurable in Settings → Error Handling & Logging. By default the cleanup cron prunes entries older than 365 days; set to 0 to keep forever.

27. Email Log

27.1 What's Recorded

Every email dispatched by HostKit is logged with:

• Recipient user ID and email address.
• Subject line.
• Email type (template key).
• Subscription ID (if applicable).
• Status: sent or failed.
• Timestamp.

27.2 Use Cases

• Confirming a customer received a specific email when they claim they didn't.
• Investigating a delivery problem (is the email failing locally before SMTP, or is the SMTP server bouncing?).
• Auditing how often a renewal reminder was sent and on what dates.
• Confirming the kill switch wasn't accidentally swallowing emails during a recent change.

28. Webhooks

28.1 Outbound Webhook Definitions

Configure webhook endpoints at Integrations → Webhooks. Each definition is a target URL plus a list of events you want to receive. Endpoints can be tested with a Send Ping button that fires a sample payload.

28.2 Supported Events

The full list of supported event types is:

28.3 Signature & Headers

Every webhook delivery includes:

• X-HK-Event — the event name.
• X-HK-Signature — HMAC-SHA256 of the raw body using the endpoint's secret. Verify this server-side to confirm the payload really came from your HostKit installation.
• Content-Type: application/json
• JSON body with the event metadata and a snapshot of the related subscription, order, or invoice.

28.4 Retry & Logging

Failed deliveries (any non-2xx response) are retried with exponential backoff. Every attempt is logged with timestamp, response code, and response body for debugging. Endpoints that fail repeatedly are eventually disabled and an admin notification fires.

29. Automation Engine

29.1 What It Is

The automation engine is a rule-based workflow runner that listens to subscription lifecycle events and executes admin-defined actions. Rules have JSON-encoded conditions and actions; every execution is logged for audit.

29.2 Triggers

Rules can fire on any of these triggers:

• subscription.created
• subscription.activated
• subscription.suspended
• subscription.reactivated
• subscription.cancelled
• subscription.terminated
• payment.failed
• renewal.completed

29.3 Conditions

Each rule has a list of conditions, all of which must pass for the rule to fire. A condition is a triple of { field, operator, value } evaluated against the subscription. Supported operators include equals, not_equals, greater_than, less_than, contains, in, and not_in.

29.4 Actions

Each rule executes one or more actions when its conditions pass. The six action types:

29.5 Example

"When a customer's payment fails and they're on the Premium plan, send them a personalized email and add an internal note for the support team":

Trigger:    payment.failed
Conditions: product_name equals "Premium"
Actions:    send_email(template = high_value_payment_failed)
            add_note("Premium customer payment failed - please follow up")

29.6 Audit Trail

Every rule firing is logged with rule ID, subscription ID, trigger, the actions executed, and a timestamp.

30. Analytics & Reporting

30.1 Headline Metrics

The Analytics page at Insights → Analytics surfaces the metrics every hosting business cares about:

30.2 Customer Lifetime Value

The CLV ranking table lists customers by their cumulative paid invoices. Click any row to drill into that customer's full history.

30.3 Overdue Aging

Unpaid invoices bucketed into 0–30, 31–60, 61–90, and 90+ days. Each bucket links to the underlying invoice list filtered to that age range.

30.4 Activity Timeline

Per-subscription unified timeline merging email log, notes, and audit log into a single chronological view. This is the same feed shown on the single hosting page.

30.5 Weekly Business Report Email

Optional weekly digest email summarising MRR, ARR, new sign-ups, churn, and trial conversions. Configured in Settings → Emails.

30.6 Data Export

Every list page (Hostings, Invoices, Users, Servers, etc.) has an Export CSV button. Exports respect the current filters — so an export of "all unpaid invoices over $100" gives you exactly that subset.

31. REST API

31.1 Namespace

All endpoints live under /wp-json/itx-hostkit/v1/.

31.2 Authentication

Authenticate with WordPress Application Passwords. Generate one at Users → Profile → Application Passwords, then pass it via Basic Auth:

curl -u 'username:xxxx xxxx xxxx xxxx xxxx xxxx' \
     https://example.com/wp-json/itx-hostkit/v1/subscriptions

The user's HostKit role determines which endpoints they can call. Read endpoints typically need a view capability; write endpoints need an edit or manage capability.

31.3 Endpoints

31.4 Pagination

List endpoints support ?page=N&per_page=M (default 10, max 100). Responses include the standard WordPress pagination headers:

X-WP-Total: 247
X-WP-TotalPages: 25

31.5 Rate Limiting

Write endpoints (POST/PUT/DELETE) are rate-limited to 60 requests per minute per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.

31.6 Errors

Errors follow the standard WordPress REST format with code, message, and HTTP status. Examples:

• 401 — missing or invalid Application Password.
• 403 — user lacks the required HostKit capability.
• 404 — subscription, server, or invoice not found.
• 409 — conflicting state (e.g., trying to terminate a subscription that's already terminated).
• 429 — rate limit exceeded.

32. Pricing Table Shortcode

32.1 Basic Usage

Drop the shortcode anywhere on a page or post:

[hk_pricing_table]

That renders a responsive 3-column pricing grid showing every WooCommerce product mapped to a WHM package. No manual configuration needed — if a plan has at least one mapping it appears.

32.2 Attributes

32.3 Examples

[hk_pricing_table billing_cycle="both" highlight="42" columns="4"]
[hk_pricing_table product_ids="10,20,30" show_button="no"]

32.4 Styling

The pricing table uses CSS classes that you can override in your theme:

• .hk-pricing-table, .hk-pricing-cols-{1-4} — outer grid.
• .hk-pricing-card, .hk-pricing-featured — card with optional Popular state.
• .hk-pricing-badge — the Popular pill.
• .hk-pricing-plan-name, .hk-pricing-price, .hk-pricing-amount, .hk-pricing-period — price display.
• .hk-pricing-features, .hk-pricing-btn, .hk-pricing-btn-featured — features and CTA.

All colours are CSS variables tied to your brand palette — never hardcoded hex — so theme changes from Settings → UI & Display propagate automatically.

32.5 Caching

Results are cached in object cache for 15 minutes. After editing prices or mappings, you can force a refresh by visiting any HostKit admin page or by clearing object cache.

33. Settings Reference

The Settings page at admin.php?page=hk-settings is split into ten tabs. The tab is selected via the ?tab=... query parameter so individual tabs are bookmarkable.

33.1 Settings Tabs

33.2 Frequently Used Options

34. Security

34.1 Encryption at Rest

WHM API tokens and TOTP secrets are encrypted with AES-256-CBC. The encryption key is generated per-installation on first activation and stored as a WordPress option. Secrets are never written in plain text.

34.2 Two-Factor Authentication

RFC 6238 TOTP with brute-force throttling (5 failed attempts = 15-minute lockout) and single-use backup codes. Available to both customers and admins.

34.3 Granular Capabilities

31 capabilities across 6 sections (Hosting, Infrastructure, Commerce, Customers, Insights, System). Use the hk_current_user_can() helper instead of current_user_can('manage_options') when adding custom code.

34.4 AJAX Rate Limiting

Every AJAX handler in HostKit is wrapped in a per-IP, per-action rate limiter. Excess requests get a throttled response and are logged to the audit log so repeated abuse is visible.

34.5 CSRF Protection

All admin forms and AJAX endpoints check a nonce verified by WordPress's standard nonce APIs. The plugin's JavaScript localizes the nonce and includes it on every AJAX call.

34.6 Database Query Hygiene

All custom queries use prepared statements; IDs are cast through integer-only sanitisation before being interpolated into table names. Repeated reads inside loops are cached in object cache.

34.7 GDPR & Privacy

HostKit registers WordPress's standard data export and erasure hooks. When an admin exports data for a user, HostKit contributes:

• All hosting subscriptions (domain, status, dates, prices).
• All invoices and credit notes (numbers, amounts, dates).
• Subscription notes and audit log entries.
• Email log entries.
• Two-factor enrollment status (but not the secret).

On erasure, customer-identifying fields are anonymised; financial records are retained per accounting requirements. Configure retention behaviour in Settings → Error Handling & Logging.

34.8 Impersonation Safety

Login as Customer is HMAC-signed, audit-logged, capped at 2 hours, blocks nested impersonation, and refuses to impersonate other administrators.

34.9 Webhook Signature

Outbound webhooks include an X-HK-Signature HMAC-SHA256 header keyed by the endpoint's secret. Always verify the signature server-side before trusting a payload.

35. Cron Jobs

35.1 Registered Jobs

35.2 Manual Run

From Settings → Cron & Scheduling you can fire any of the above jobs immediately for testing or to recover from a missed run. Missed runs are also caught the next time the cron triggers (WP-Cron only fires when WordPress receives traffic).

35.3 Real Cron Recommendation

36. Database Reference

36.1 Table Map

36.2 Subscription Status Constants

Use the constants instead of raw strings in custom code:

HK_STATUS_ACTIVE      // 'active'
HK_STATUS_SUSPENDED   // 'suspended'
HK_STATUS_PENDING     // 'pending'
HK_STATUS_CANCELLED   // 'cancelled'
HK_STATUS_TERMINATED  // 'terminated'
HK_STATUS_EXPIRED     // 'expired'
HK_STATUS_ON_HOLD     // 'on-hold'
HK_STATUS_FAILED      // 'failed'

36.3 Plugin Constants

HK_VERSION             // current plugin version
HK_PLUGIN_DIR          // plugin directory path
HK_PLUGIN_URL          // plugin directory URL
HK_PLUGIN_FILE         // main plugin file
HK_VENDOR_DIR          // vendor directory

37. Troubleshooting

37.1 Account creation fails on a new server

1. Click Test Connection on the server card. If it fails, your token or hostname is wrong.
2. Confirm WHM API tokens are enabled and the token has the create-account permission.
3. Check the audit log entry for the failed provisioning attempt — the WHM error message is included verbatim.
4. Confirm the server's account limit hasn't been reached.
5. Check the provision queue at the audit log to see if the row is queued for retry or marked permanently failed.

37.2 Renewal emails aren't sending

• Visit Insights → Email Log — look for the email type. If it's there with status failed the issue is delivery (check your SMTP plugin and server logs).
• If the email isn't in the log, the cron didn't fire. Check WP-Cron health under Settings → Cron & Scheduling.
• Confirm the email kill switch isn't on (Settings → Emails → Disable email notifications).
• Confirm the customer's email isn't bouncing — bounce-tracking has to come from your SMTP provider.

37.3 Plan change isn't applying

• Customer-initiated upgrades apply immediately with proration.
• Customer-initiated downgrades auto-schedule for the next renewal.
• Admin-initiated changes land in the review queue. Go to Hosting → Plan Changes and use Schedule, Change Immediately, or Cancel.
• If a scheduled change didn't fire on its date, check that the daily plan-change cron ran (Cron & Scheduling tab).

37.4 Customer can't access the Invoices tab in My Account

The Invoices tab requires a permalink flush. Visit Settings → Permalinks and click Save without changing anything (or deactivate and reactivate the plugin).

37.5 Login as Customer button is missing

The button requires the hk_impersonate_customers capability. WordPress administrators always have it; for non-admin staff add it to their HostKit role at Users & Access → Roles & Permissions.

37.6 Where do I find debug logs?

HostKit writes to a dedicated debug log when Settings → Error Handling & Logging → Enable debug log is on. The file lives in wp-content/uploads/hk-logs/ with a hardened .htaccess. The settings page has a Download Log button.