Adds a Billable Item

Request Parameters

Parameter Type Description Required
action string “AddBillableItem” Required
clientid int The client to add the item to Required
description string The description of the Billable Item. This will appear on the invoice Required
amount float the total amount to invoice for Required
invoiceaction string One of ‘noinvoice’, ‘nextcron’, ‘nextinvoice’, ‘duedate’, ‘recur’ Optional
recur int When $invoiceaction=recur. The frequency of the recurrence. Optional
recurcycle string How often to recur the Billable Item. Days, Weeks, Months or Years. Optional
recurfor int How many times the Billable Item should create an invoice. Optional
duedate \Carbon\Carbon Date the invoice should be due (only required for duedate & recur invoice actions). YYYY-mm-dd Optional
hours float number of hours/quantity the item corresponds to. (not required for single quantities) Optional

Response Parameters

Parameter Type Description
result string The result of the operation: success or error
billableid int The id of the newly created billable item

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, '');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
            'action' => 'AddBillableItem',
            // See
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'clientid' => '1',
            'description' => 'This is a billable item',
            'amount' => '10.00',
            'invoiceaction' => 'recur',
            'recur' => '1',
            'recurcycle' => 'Months',
            'recurfor' => '12',
            'duedate' => '2016-01-01',
            'responsetype' => 'json',
$response = curl_exec($ch);

Example Request (Local API)

$command = 'AddBillableItem';
$postData = array(
    'clientid' => '1',
    'description' => 'This is a billable item',
    'amount' => '10.00',
    'invoiceaction' => 'recur',
    'recur' => '1',
    'recurcycle' => 'Months',
    'recurfor' => '12',
    'duedate' => '2016-01-01',
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);

Example Response JSON

    "result": "success",
    "billableid": "1"

Error Responses

Possible error condition responses include:

  • Client ID not Found
  • You must provide a description
  • Invalid Invoice Action
  • Recurring must have a unit, cycle and limit
  • Due date is required

Version History

Version Changelog
1.0 Initial Version