Skip to main content

User Guide

MX Proposals for WHMCS

Professional Proposals with Digital Signatures & Payment Plans

Version 1.1.0 · Complete documentation

Last updated: February 2026

Installation

Estimated time: 10 minutes

Requirements: WHMCS 8.0+, PHP 8.0+

Step 1: Upload Addon Files

  1. 1.Extract mx_proposals.zip
  2. 2.Upload the proposals/ folder to /modules/addons/

Expected folder structure:

/whmcs/modules/addons/proposals/
├── proposals.php
├── hooks.php
├── viewer.php
├── download.php
├── lib/
├── templates/
├── assets/
└── fonts/

Step 2: Upload Proposal Viewer

Upload the proposal/ folder to your WHMCS root directory. This enables friendly URLs for client proposals.

Result:

/whmcs/proposal/
├── index.php
└── .htaccess

Result: Clients access proposals at yourdomain.com/proposal/abc123

Step 3: Activate & Configure

  1. 1.Go to Configuration → Addon Modules
  2. 2.Find "Proposals" and click Activate
  3. 3.Set Access Control to "Full Administrator"
  4. 4.Click Save Changes

Done! Access MX Proposals from Addons → Proposals in the admin menu.

Feature Overview

MX Proposals adds a complete proposal management system to WHMCS. Send proposals to clients, collect signatures and deposits, and let WHMCS handle the rest.

Digital Signatures

Clients sign proposals directly in their browser with a signature pad.

Deposit Collection

Collect a deposit on acceptance. Configurable as percentage or fixed amount.

Payment Plans

Split payments into installments with automatic invoice generation. (Pro)

Video & PDF Embeds

Attach videos and PDF documents to proposals for richer presentations. (Pro)

Custom Branding

Set your logo, colors, fonts, and style presets for a professional look. (Pro)

Automatic Orders

When a client accepts, WHMCS creates the order and invoices automatically.

Email Notifications

Automatic emails for sent, viewed, accepted, and expired proposals.

Webhooks

HTTP POST notifications for proposal events. Connect n8n, Zapier, or custom apps. (Pro)

Creating a Proposal

Step 1: Start a New Proposal

Go to Addons → Proposals and click Create Proposal. Enter a title, select a client (or leave blank for a new lead), and set the validity period.

Step 2: Add Services

Add line items with description, quantity, and unit price. You can mark items as optional. Set a deposit amount (percentage or fixed) that the client pays on acceptance.

Step 3: Add Media (Pro)

Attach a video introduction (YouTube or Vimeo URL) and PDF documents like service agreements or brochures. Clients see these embedded directly in the proposal.

Step 4: Configure Payment (Pro)

Set up a payment plan to split the remaining balance into installments. Choose the number of payments, frequency, and start date. Invoices are generated automatically on schedule.

Step 5: Send

Click Send Proposal. The client receives an email with a unique link. You can track views, resend, or revoke from the proposals dashboard.

Settings

Configure MX Proposals from Addons → Proposals → Settings.

Countries & Form Fields

Set which countries appear in the client form. Configure visibility of phone, company, tax ID, and address fields (optional, required, or hidden).

Branding (Pro)

Upload your logo, set primary and accent colors, choose fonts, and select a style preset (Classic, Modern, Dark). Add custom CSS and footer text.

Email Templates

Customize the emails sent when proposals are created, viewed, accepted, or expired. Set sender name and email address.

Signature

Enable or disable digital signatures globally. Allow per-proposal override so you can skip signatures for smaller deals.

Payment

Set default invoice due days, minimum deposit requirements, and notes that appear on generated invoices.

Automation (Pro)

Set a webhook URL to receive HTTP POST notifications when proposal events happen. Optionally add a webhook secret for HMAC-SHA256 signature verification.

Defaults

Set the default validity period, currency, and notes template for new proposals.

Webhooks (Pro)

Webhooks send HTTP POST requests to your endpoint when proposal events occur. Use them to trigger external workflows in n8n, Zapier, Slack, or any custom application.

Configuration

Go to Addons → Proposals → Settings → Automation tab.

Webhook URL

The endpoint that receives POST requests. Example: https://your-app.com/webhook

Webhook Secret (optional)

A shared secret for HMAC-SHA256 signature verification. When set, each request includes an X-Proposals-Signature header you can verify.

Events

EventWhen
proposal.sentProposal is sent to the client
proposal.viewedClient opens the proposal link
proposal.acceptedClient signs and accepts the proposal
proposal.paidPayment is processed successfully
proposal.declinedClient declines the proposal
proposal.expiredProposal auto-expires past its deadline

Request Format

Each webhook sends a JSON POST with these headers:

Content-Type: application/json
X-Proposals-Event: proposal.accepted
X-Proposals-Signature: <HMAC-SHA256 hash>
X-Proposals-Timestamp: 1740234567

Example payload:

{
  "event": "proposal.accepted",
  "timestamp": 1740234567,
  "proposal": {
    "id": 42,
    "title": "Web Redesign Project",
    "status": "accepted",
    "token": "abc123def456",
    "total": "1500.00",
    "deposit": "750.00"
  },
  "client": {
    "email": "john@example.com",
    "name": "John Doe"
  }
}

Verifying Signatures

If you set a webhook secret, verify the X-Proposals-Signature header by computing the HMAC-SHA256 hash of the raw request body using your secret:

$secret = 'your-webhook-secret';
$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $secret);
$received = $_SERVER['HTTP_X_PROPOSALS_SIGNATURE'];

if (hash_equals($expected, $received)) {
    // Signature valid - process the webhook
}

Free vs Pro

MX Proposals is freemium. The Free version covers the essentials. Pro unlocks unlimited proposals, payment plans, and full customization.

FeatureFreePro
Active proposals5Unlimited
Digital signatures
Deposit collection
Automatic orders & invoices
PDF attachments1Unlimited
Video embeds
Payment plans
Custom branding
Style presetsClassicAll
Proposal templates
Email customization
Webhooks (6 events)
Advanced analytics

Frequently Asked Questions

What is the difference between Free and Pro?

The Free version includes up to 5 active proposals, digital signatures, deposit collection, and 1 PDF attachment per proposal. Pro adds unlimited proposals, payment plans, video embeds, custom branding, style presets, proposal cloning, email customization, and advanced analytics.

How do clients view and sign proposals?

Clients receive an email with a unique link to their proposal. The proposal page shows all details including services, pricing, attachments, and a signature pad. After signing and paying the deposit, an order is automatically created in WHMCS.

Does MX Proposals create invoices automatically?

Yes. When a client accepts a proposal and pays the deposit, MX Proposals automatically creates a WHMCS order and generates invoices. For payment plans (Pro), installment invoices are created on the scheduled dates.

Can I customize the proposal appearance?

Yes. Pro users can set custom colors, logos, fonts, and style presets (Classic, Modern, Dark). You can also add custom CSS and footer text. Free users get the Classic style preset.

Which payment gateways are supported?

MX Proposals works with all WHMCS payment gateways. You can restrict which gateways are available per proposal if needed.

Which WHMCS versions are supported?

MX Proposals supports WHMCS 8.0 and newer. We recommend using the latest stable version (8.8+) for best compatibility.

How do webhooks work?

Pro includes webhooks that send HTTP POST requests to your endpoint when proposal events happen (sent, viewed, accepted, paid, declined, expired). Configure a URL in Settings > Automation. Optionally add a secret for HMAC-SHA256 signature verification. Use webhooks to connect n8n, Zapier, Slack, or any custom application.

Use AI to Manage Proposals

Connect Claude Desktop, OpenAI Codex, or Cursor to WHMCS Proposals. Create, update, and send proposals using natural language.

MCP Server Setup Guide

Need Help?

Our support team is ready to assist you with any questions about MX Proposals.

Contact SupportView Product Page