Skip to content
Last updated

AddBillableItem

Adds a Billable Item

Request Parameters

ParameterTypeDescriptionRequired
actionstring"AddBillableItem"Required
clientidintThe client to add the item to.Required
descriptionstringThe description of the Billable Item. This will appear on the invoice.Required
amountfloatThe total amount to invoice for.Required
unitstringEither 'hours' or 'quantity'.Required
quantityfloatThe number of units the billable items represents. Defaults to 0.Optional
invoiceactionstringOne of 'noinvoice', 'nextcron', 'nextinvoice', 'duedate', or 'recur'.Optional
recurintWhen $invoiceaction=recur. The frequency of the recurrence.Optional
recurcyclestringHow often to recur the Billable Item. Days, Weeks, Months or Years.Optional
recurforintHow many times the Billable Item should create an invoice.Optional
duedatestringDate the invoice should be due (only required for due date and recur invoice actions). YYYY-mm-ddOptional

Response Parameters

ParameterTypeDescription
resultstringThe result of the operation: success or error
billableidintThe ID of the newly created billable item.

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddBillableItem',
            // See https://developers.whmcs.com/api/authentication
            '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' => '2021-01-01',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($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' => '2021-01-01',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

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

Example Response JSON

{
    "status": "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
  • Invalid Unit, please specify either 'hours' or 'quantity'
  • Invalid Date Format - Expected: 'YYYY-mm-dd'

Version History

VersionChangelog
1.0Initial Version
8.2Renamed 'hours' parameter to quantity. Now Required
8.2Added unit parameter.