The following hooks are provided for Shopping Cart related events.
Runs when an order is accepted prior to any acceptance actions being executed.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The order ID |
No response supported
<?php
add_hook('AcceptOrder', 1, function($vars) {
// Perform hook code here...
});Executes when an addon is set as fraud.
| Variable | Type | Notes |
|---|---|---|
| id | int | The addon ID (tblhostingaddons) |
| userid | int | |
| serviceid | int | |
| addonid | int | The predefined addon ID (tbladdons) |
No response supported
<?php
add_hook('AddonFraud', 1, function($vars) {
// Perform hook code here...
});Executes after the cart totals have been calculated.
| Variable | Type | Notes |
|---|---|---|
| total | \Price | Total due today |
No response supported
<?php
add_hook('AfterCalculateCartTotals', 1, function($vars) {
// Perform hook code here...
});Executes after a fraud check has been completed
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The id of the order that has been fraud checked |
| ordernumber | int | The order number |
| invoiceid | int | The ID of the invoice generated on order |
| amount | float | The amount the order was for |
| fraudresults | array | The full result from the fraud check |
| isfraud | bool | Has the check been deemed as fraud |
| frauderror | array | The details of the fraud check if an error occurs |
| clientdetails | array | The full details of the client the order is for |
No response supported
<?php
add_hook('AfterFraudCheck', 1, function($vars) {
// Perform hook code here...
});Upon completion of checkout once the order has been created, invoice generated and all email notifications sent.
| Variable | Type | Notes |
|---|---|---|
| OrderID | int | The Order ID |
| OrderNumber | int | The randomly generated order number |
| ServiceIDs | array | An array of Service IDs created by the order |
| AddonIDs | array | An array of Addon IDs created by the order |
| DomainIDs | array | An array of Domain IDs created by the order |
| RenewalIDs | array | An array of Domain Renewal IDs created by the order |
| PaymentMethod | string | The payment gateway selected |
| InvoiceID | int | The Invoice ID |
| TotalDue | float | The total amount due |
No response supported
<?php
add_hook('AfterShoppingCartCheckout', 1, function($vars) {
// Perform hook code here...
});Runs when an order is requested to be cancelled, prior to the change of status actually occurring.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The order ID |
No response supported
<?php
add_hook('CancelOrder', 1, function($vars) {
// Perform hook code here...
});Invoked as tax is being calculated for both cart and checkout, this can be used to manipulate the tax rate applied to the cart total or relevant checkout payment intents.
| Variable | Type | Notes |
|---|---|---|
| clientData | array | null |
| cartData | \ItemInterface[] | An array of all data held within in the shopping cart. |
Return an array of the manipulated ItemInterface items. Tax will be calculated from the delta of the original items.
<?php
use WHMCS\View\Formatter\Price;
add_hook('CartItemsTax', '1', function ($vars) {
$cartItems = $vars['cartData'];
$client = $vars['clientData'];
// Calculate your tax rate to apply
$taxRate = 1.5; // 50%
/** @var \WHMCS\Cart\Item\ItemInterface $item */
foreach ($cartItems as $item) {
if (!$item->isTaxed()) {
continue;
}
/** @var Price $amountToday */
$amountToday = $item->getAmount();
// Set the price due today for the item
$item->setAmount(new Price(
($amountToday->toNumeric() * $taxRate),
$amountToday->getCurrency()
));
if ($item->isRecurring()) {
/** @var Price $recurringAmount */
$recurringAmount = $item->getRecurringAmount();
// Set the recurring price of the item
$item->setRecurringAmount(
new Price(
($recurringAmount->toNumeric() * $taxRate),
$recurringAmount->getCurrency()
)
);
}
}
return [
'cartData' => $cartItems
];
});Executes when Cart Subdomain Validation is occurring
| Variable | Type | Notes |
|---|---|---|
| subdomain | string | eg sub in sub.whmcs.com |
| domain | string | eg whmcs.com in sub.whmcs.com |
Return any validation errors. eg: return array('error1', 'error2',);
<?php
add_hook('CartSubdomainValidation', 1, function($vars) {
// Perform hook code here...
});Invoked as the order total is being calculated, this can be used to manipulate the final total.
| Variable | Type | Notes |
|---|---|---|
| products | array | An indexed array of products in the shopping cart. Keys include pid, domain, billingcycle, configoptions, customfields, addons, server, hostname |
| domains | array | An indexed array of domain registrations & transfers in the shopping cart. Keys include type, domain, regperiod |
Return an array consisting of adjustment description, amount and taxed (bool)
<?php
add_hook('CartTotalAdjustment', 1, function($vars) {
$cart_adjustments = array();
$products = $tlds = [];
foreach ($vars['products'] as $product) {
$products[] = $product['pid'];
}
foreach ($vars['domains'] as $domain) {
if ($domain['type'] == 'register') {
$domainParts = explode('.', $domain['domain'], 2);
$tlds[] = $domainParts[1];
}
}
if (in_array(1, $products) && in_array('co.uk', $tlds)) {
$cart_adjustments = [
"description" => "Custom discount for buying product 1 and a co.uk domain",
"amount" => "-18.00",
"taxed" => false,
];
}
return $cart_adjustments;
});Runs when an order is requested to be deleted, prior to the deletion actually occurring.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The order ID |
No response supported
<?php
add_hook('DeleteOrder', 1, function($vars) {
// Perform hook code here...
});Executes when the fraud check is awaiting user input.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The id of the order that has been fraud checked |
| ordernumber | int | The order number |
| invoiceid | int | The ID of the invoice generated on order |
| amount | float | The amount the order was for |
| fraudresults | array | The full result from the fraud check |
| isfraud | array | The details of the fraud check if an error occurs |
| clientdetails | array | The full details of the client the order is for |
No response supported
<?php
add_hook('FraudCheckAwaitingUserInput', 1, function($vars) {
// Perform hook code here...
});Executes when the fraud check fails for a new order.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The id of the order that has been fraud checked |
| ordernumber | int | The order number |
| invoiceid | int | The ID of the invoice generated on order |
| amount | float | The amount the order was for |
| fraudresults | array | The full result from the fraud check |
| isfraud | array | The details of the fraud check if an error occurs |
| clientdetails | array | The full details of the client the order is for |
No response supported
<?php
add_hook('FraudCheckFailed', 1, function($vars) {
// Perform hook code here...
});Executes when the fraud check passes successfully for a new order.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The id of the order that has been fraud checked |
| ordernumber | int | The order number |
| invoiceid | int | The ID of the invoice generated on order |
| amount | float | The amount the order was for |
| fraudresults | array | The full result from the fraud check |
| isfraud | array | The details of the fraud check if an error occurs |
| clientdetails | array | The full details of the client the order is for |
No response supported
<?php
add_hook('FraudCheckPassed', 1, function($vars) {
// Perform hook code here...
});Runs when an order is requested to be set as fraud, prior to the change of status actually occurring.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The order ID |
No response supported
<?php
add_hook('FraudOrder', 1, function($vars) {
// Perform hook code here...
});Executes as an addon price is being calculated in the cart.
| Variable | Type | Notes |
|---|---|---|
| key | int | The key for the product in the cart session |
| pid | int | The product id |
| addonid | int | The addon id |
| proddata | array | The product data for an addon with new product purchase |
| serviceid | int | The service id when purchasing an addon for existing service |
Addon pricing can be overridden. Accepts a return of the keys 'setup' and 'recurring'.
<?php
use WHMCS\Service\Service;
add_hook('OrderAddonPricingOverride', 1, function($vars) {
$return = [];
if (array_key_exists('proddata', $vars)) {
/**
* This is a product and addon purchase
*/
if ($vars['addonid'] == 1 && $vars['proddata']['pid'] == 1) {
$return = ['setup' => '1.00', 'recurring' => '5.00',];
}
} else {
/**
* This is an addon only purchase for existing service
*/
$serviceData = Service::find($vars['serviceid']);
if ($serviceData && $vars['addonid'] == 1 && $serviceData->packageId == 1) {
$return = ['setup' => '1.00', 'recurring' => '5.00',];
}
}
return $return;
});Executes as a domain price is being calculated in the cart.
| Variable | Type | Notes |
|---|---|---|
| type | string | Either register or transfer |
| domain | string | |
| regperiod | int | The registration period of the domain (in years) |
| renewalperiod | int | The renewal period of the domain (in years) |
| dnsmanagement | bool | |
| emailforwarding | bool | |
| idprotection | bool | |
| eppcode | string | Available for transfer only. |
| isPremium | bool |
A float to override the first payment, or an array to override first and/or recurring amounts
<?php
add_hook('OrderDomainPricingOverride', 1, function($vars) {
// Perform operations to determine price.
// To override the first payment amount only simply return a float
return '64.95';
// To override the first payment and recurring amount, return an array as follows
return ['firstPaymentAmount' => 64.95, 'recurringAmount' => 14.45];
});Executes when the first invoice for a new order is marked paid. This will execute in addition to the regular invoice payment hooks.
| Variable | Type | Notes |
|---|---|---|
| orderId | int | The unique identifier for the order |
| userId | int | The unique identifier for the client |
| invoiceId | int | The unique identifier for the invoice |
No response supported
<?php
add_hook('OrderPaid', 1, function($vars) {
// Perform hook code here...
});Executes as a product price is being calculated in the cart.
| Variable | Type | Notes |
|---|---|---|
| key | int | The key for the product in the cart session |
| pid | int | The product id |
| proddata | array | The product data |
Product pricing can be overridden - exclusive of configurable option cost. Accepts a return of the keys 'setup' and 'recurring'. eg: return array('setup' => 1.00, 'recurring' => 12.00);
<?php
use WHMCS\Authentication\CurrentUser;
add_hook('OrderProductPricingOverride', 1, function($vars) {
$return = [];
/**
* Get the logged in client. Returns null if no client logged in.
*
* @see https://developers.whmcs.com/advanced/authentication/
*/
$client = CurrentUser::client();
/**
* Run the following rules if a Client is logged in.
*/
if ($client) {
/**
* Override the product price when ordering product 1 and the user has the ID 10.
*/
if ($vars['pid'] == 1 && $client->id == 10) {
$return = ['setup' => '0.00', 'recurring' => '0.00',];
}
/**
* Override the product price when user has the ID 72.
*/
if ($client->id == 72) {
$return = ['setup' => '0.00', 'recurring' => '0.00',];
}
}
return $return;
});Executes as a product upgrade order is being calculated.
| Variable | Type | Notes |
|---|---|---|
| oldproductid | int | |
| oldproductname | string | |
| newproductid | int | |
| newproductname | string | |
| days | int | |
| totaldays | int | |
| newproductbillingcycle | string | |
| price | float | |
| discount | float | |
| promoqualifies | bool |
Return any key -> value pairs of the parameters to override. eg return array('discount' => 10.00,);
<?php
use WHMCS\Carbon;
add_hook('OrderProductUpgradeOverride', 1, function($vars) {
$return = [];
if ($vars['newproductid'] == 15) {
/**
* No promotion should be applied to product 15
*/
$return['promoqualifies'] = false;
}
if (Carbon::now()->toDateString() == '2016-12-25') {
/**
* Offer half price upgrade on Christmas Day
* This can also be done by halving the $vars['price'] and returning that.
*/
$return['totaldays'] = round($vars['totaldays'] / 2);
}
return $return;
});Executes prior to checkout. All cart information is passed to the hook.
| Variable | Type | Notes |
|---|---|---|
| products | array | An indexed array of product information for each product in the cart. |
| domains | array | An indexed array of domain information for each domain in the cart. |
Return the custom order number to be used (must be a valid numeric value).
<?php
add_hook('OverrideOrderNumberGeneration', 1, function($vars) {
// Generate and return a custom order number value (must be a valid integer).
// We also recommend ensuring the custom number is unique.
return time();
});Runs when an order is requested to be set back to pending, prior to the change of status actually occurring.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The order ID |
No response supported
<?php
add_hook('PendingOrder', 1, function($vars) {
// Perform hook code here...
});Executes as the cart totals are being calculated. All cart information is passed to the hook. Examples given here.
| Variable | Type | Notes |
|---|---|---|
| products | array | An indexed array of product information for each product in the cart. |
| domains | array | An indexed array of domain information for each domain in the cart. |
No response supported
<?php
add_hook('PreCalculateCartTotals', 1, function($vars) {
// Perform hook code here...
});| Variable | Type | Notes |
|---|---|---|
| $params |
No response supported
<?php
add_hook('PreFraudCheck', 1, function($vars) {
// Perform hook code here...
});Executes prior to checkout. All cart information is passed to the hook.
| Variable | Type | Notes |
|---|---|---|
| products | array | An indexed array of product information for each product in the cart. |
| domains | array | An indexed array of domain information for each domain in the cart. |
No response supported
<?php
add_hook('PreShoppingCartCheckout', 1, function($vars) {
// Perform hook code here...
});Executes as the fraud module is being checked for an order.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | |
| userid | int |
Return any value to skip the fraud check
<?php
add_hook('RunFraudCheck', 1, function($vars) {
// Perform hook code here...
});Executes when the Complete Page is displayed on checkout.
| Variable | Type | Notes |
|---|---|---|
| orderid | int | The ID of the order |
| ordernumber | int | The order number for the order |
| invoiceid | int | The id of the invoice for the order |
| ispaid | bool | Indicates whether the order has been paid |
| amount | float | The amount of order |
| paymentmethod | string | The payment method of the order |
| clientdetails | array | The full details for the client the order is for |
Return HTML to be displayed on the order complete page.
<?php
add_hook('ShoppingCartCheckoutCompletePage', 1, function($vars) {
/**
* Redirect all orders to a different page after the order complete page is loaded.
*/
return '<META http-equiv="refresh" content="5;URL=http://www.mydomain.com/ownpage.html" />';
});Executes during checkout completion, which occurs before order and invoice creation. Use this to prevent order creation and present errors to the user.
| Variable | Type | Notes |
|---|---|---|
| a | string | Value will be checkout. |
| submit | string | Value will be true. |
| promocode | string | If entered, a promotion code. |
| notes | string | If enabled, additional order notes |
| paymentmethod | string | The selected payment method |
| ccinfo | string | Either new or useexisting. |
| cctype | string | |
| ccnumber | string | |
| ccexpirymonth | string | |
| ccexpiryyear | string | |
| cccvv | string | |
| custtype | string | Possible values are new or existing |
| clientId | int | A non-zero value if the user is authenticated during checkout. |
| loginemail | string | Value present only when the client authenticates during checkout. |
| loginpassword | string | Value present only when the client authenticates during checkout. |
| firstname | string | Value present when the client is new. |
| lastname | string | Value present when the client is new. |
| companyname | string | Value present when client is new |
| string | Value present when client is new | |
| address1 | string | Value present when client is new |
| address2 | string | Value present when client is new |
| city | string | Value present when client is new |
| state | string | Value present when client is new |
| country | string | Value present when client is new; two letter ISO code |
| tax_id | string | The client's tax ID |
| phonenumber | string | Value present when client is new |
| password | string | Value present when client is new |
| password2 | string | Value present when client is new |
| securityqid | string | Value present when client is new |
| securityqans | string | Value present when client is new |
| customfield | array | Value present when client is new |
Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.
<?php
add_hook('ShoppingCartValidateCheckout', 1, function($vars) {
return [
'Error message feedback error 1',
'Error message feedback error 2',
];
});Executes when Cart Domain Validation is occurring
| Variable | Type | Notes |
|---|---|---|
| domainoption | string | |
| sld | string | eg whmcs in whmcs.com |
| tld | string | eg com in whmcs.com |
Return any validation errors. eg: return array('error1', 'error2',);
<?php
add_hook('ShoppingCartValidateDomain', 1, function($vars) {
return [
'Error message feedback error 1',
'Error message feedback error 2',
];
});Executes when Domain Update is occurring
| Variable | Type | Notes |
|---|---|---|
| N/A | array | The REQUEST variables |
Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.
<?php
add_hook('ShoppingCartValidateDomainsConfig', 1, function($vars) {
return [
'Error message feedback error 1',
'Error message feedback error 2',
];
});Executes when Product Update is occurring
| Variable | Type | Notes |
|---|---|---|
| N/A | array | The REQUEST variables |
Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.
<?php
add_hook('ShoppingCartValidateProductUpdate', 1, function($vars) {
return [
'Error message feedback error 1',
'Error message feedback error 2',
];
});Executes during an upgrade/downgrade request to validate resource limits.
| Variable | Type | Notes |
|---|---|---|
| id | int | ID of the existing hosting service |
| pid | int | ID of the target product for upgrade |
An array of error messages. Return an empty array to allow the upgrade.
<?php
use WHMCS\Service\Service;
use WHMCS\Product\Product;
Hook::add('ShoppingCartValidateUpgrade', 1, function($vars) {
try {
$actualHosting = Service::findOrFail($vars['id']);
$requestedUpgrade = Product::findOrFail($vars['pid']);
if ($requestedUpgrade->overageDiskLimit == 0 && $requestedUpgrade->overageBandwidthLimit == 0) {
return [];
}
if (
$actualHosting->diskUsage > $requestedUpgrade->overageDiskLimit
|| $actualHosting->bandwidthUsage > $requestedUpgrade->overageBandwidthLimit
) {
return [
'Your current disk or bandwidth usage exceeds the limits of the chosen product. <br /><br />Please reduce usage or select a higher plan.',
];
}
return [];
} catch (\Exception $e) {
return [
'Error message feedback error 1',
'Error message feedback error 2',
];
}
});