whmcs_create_invoice
Create a new invoice for a client in WHMCS by specifying client ID, status, payment method, tax rates, dates, and line items.
Instructions
Create a new invoice for a client
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| userid | Yes | Client ID | |
| status | No | Invoice status | |
| sendinvoice | No | Send invoice email | |
| paymentmethod | No | Payment method | |
| taxrate | No | Tax rate percentage | |
| taxrate2 | No | Second tax rate percentage | |
| date | No | Invoice date (YYYY-MM-DD) | |
| duedate | No | Due date (YYYY-MM-DD) | |
| notes | No | Invoice notes | |
| itemdescription | No | Line item descriptions | |
| itemamount | No | Line item amounts | |
| itemtaxed | No | Line items taxed flags |
Implementation Reference
- src/whmcs-client.ts:503-524 (handler)The createInvoice method in WhmcsApiClient that implements the tool logic by calling the WHMCS 'CreateInvoice' API action using the generic HTTP client./** * Create an invoice */ async createInvoice(params: { userid: number; status?: 'Draft' | 'Unpaid' | 'Paid' | 'Cancelled' | 'Refunded' | 'Collections'; sendinvoice?: boolean; paymentmethod?: string; taxrate?: number; taxrate2?: number; date?: string; duedate?: string; notes?: string; itemdescription?: string[]; itemamount?: number[]; itemtaxed?: boolean[]; }) { return this.call<WhmcsApiResponse & { invoiceid: number; status: string; }>('CreateInvoice', params); }
- src/index.ts:297-323 (registration)Registers the whmcs_create_invoice tool with the MCP server, including title, description, Zod input schema for validation, and thin async handler delegating to whmcsClient.createInvoice.server.registerTool( 'whmcs_create_invoice', { title: 'Create Invoice', description: 'Create a new invoice for a client', inputSchema: { userid: z.number().describe('Client ID'), status: z.enum(['Draft', 'Unpaid', 'Paid', 'Cancelled', 'Refunded', 'Collections']).optional().describe('Invoice status'), sendinvoice: z.boolean().optional().describe('Send invoice email'), paymentmethod: z.string().optional().describe('Payment method'), taxrate: z.number().optional().describe('Tax rate percentage'), taxrate2: z.number().optional().describe('Second tax rate percentage'), date: z.string().optional().describe('Invoice date (YYYY-MM-DD)'), duedate: z.string().optional().describe('Due date (YYYY-MM-DD)'), notes: z.string().optional().describe('Invoice notes'), itemdescription: z.array(z.string()).optional().describe('Line item descriptions'), itemamount: z.array(z.number()).optional().describe('Line item amounts'), itemtaxed: z.array(z.boolean()).optional().describe('Line items taxed flags'), }, }, async (params) => { const result = await whmcsClient.createInvoice(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; } );
- src/index.ts:302-316 (schema)Zod schema defining the input parameters and validation for the whmcs_create_invoice tool, matching WHMCS CreateInvoice API requirements.inputSchema: { userid: z.number().describe('Client ID'), status: z.enum(['Draft', 'Unpaid', 'Paid', 'Cancelled', 'Refunded', 'Collections']).optional().describe('Invoice status'), sendinvoice: z.boolean().optional().describe('Send invoice email'), paymentmethod: z.string().optional().describe('Payment method'), taxrate: z.number().optional().describe('Tax rate percentage'), taxrate2: z.number().optional().describe('Second tax rate percentage'), date: z.string().optional().describe('Invoice date (YYYY-MM-DD)'), duedate: z.string().optional().describe('Due date (YYYY-MM-DD)'), notes: z.string().optional().describe('Invoice notes'), itemdescription: z.array(z.string()).optional().describe('Line item descriptions'), itemamount: z.array(z.number()).optional().describe('Line item amounts'), itemtaxed: z.array(z.boolean()).optional().describe('Line items taxed flags'), }, },
- src/whmcs-client.ts:29-63 (helper)Generic API client method used by createInvoice to send authenticated POST requests to WHMCS API, handles param flattening, error checking, and JSON response parsing.async call<T extends WhmcsApiResponse>(action: string, params: Record<string, unknown> = {}): Promise<T> { const url = `${this.config.apiUrl.replace(/\/$/, '')}/includes/api.php`; const postData: Record<string, string> = { identifier: this.config.apiIdentifier, secret: this.config.apiSecret, action: action, responsetype: 'json', ...this.flattenParams(params) }; if (this.config.accessKey) { postData.accesskey = this.config.accessKey; } const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams(postData).toString(), }); if (!response.ok) { throw new Error(`WHMCS API request failed: ${response.status} ${response.statusText}`); } const data = await response.json() as T; if (data.result === 'error') { throw new Error(`WHMCS API error: ${data.message || 'Unknown error'}`); } return data; }