Shopping Cart

The following hooks are provided for Shopping Cart related events.

AcceptOrder

Runs when an order is accepted prior to any acceptance actions being executed.

Parameters

Response

No response supported

Example Code

<?php
add_hook('AcceptOrder', 1, function($vars) {
    // Perform hook code here...
});

AddonFraud

Executes when an addon is set as fraud.

Parameters

Response

No response supported

Example Code

<?php
add_hook('AddonFraud', 1, function($vars) {
    // Perform hook code here...
});

AfterCalculateCartTotals

Executes after the cart totals have been calculated.

Parameters

Response

No response supported

Example Code

<?php
add_hook('AfterCalculateCartTotals', 1, function($vars) {
    // Perform hook code here...
});

AfterFraudCheck

Executes after a fraud check has been completed

Parameters

Response

No response supported

Example Code

<?php
add_hook('AfterFraudCheck', 1, function($vars) {
    // Perform hook code here...
});

AfterShoppingCartCheckout

Upon completion of checkout once the order has been created, invoice generated and all email notifications sent.

Parameters

Response

No response supported

Example Code

<?php
add_hook('AfterShoppingCartCheckout', 1, function($vars) {
    // Perform hook code here...
});

CancelOrder

Runs when an order is requested to be cancelled, prior to the change of status actually occurring.

Parameters

Response

No response supported

Example Code

<?php
add_hook('CancelOrder', 1, function($vars) {
    // Perform hook code here...
});

CartItemsTax

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.

Parameters

Response

Return an array of the manipulated ItemInterface items. Tax will be calculated from the delta of the original items.

Example Code

<?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
    ];
});

CartSubdomainValidation

Executes when Cart Subdomain Validation is occurring

Parameters

Response

Return any validation errors. eg: return array(‘error1’, ‘error2’,);

Example Code

<?php
add_hook('CartSubdomainValidation', 1, function($vars) {
    // Perform hook code here...
});

CartTotalAdjustment

Invoked as the order total is being calculated, this can be used to manipulate the final total.

Parameters

Response

Return an array consisting of adjustment description, amount and taxed (bool)

Example Code

<?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;
});

DeleteOrder

Runs when an order is requested to be deleted, prior to the deletion actually occurring.

Parameters

Response

No response supported

Example Code

<?php
add_hook('DeleteOrder', 1, function($vars) {
    // Perform hook code here...
});

FraudCheckAwaitingUserInput

Executes when the fraud check is awaiting user input.

Parameters

Response

No response supported

Example Code

<?php
add_hook('FraudCheckAwaitingUserInput', 1, function($vars) {
    // Perform hook code here...
});

FraudCheckFailed

Executes when the fraud check fails for a new order.

Parameters

Response

No response supported

Example Code

<?php
add_hook('FraudCheckFailed', 1, function($vars) {
    // Perform hook code here...
});

FraudCheckPassed

Executes when the fraud check passes successfully for a new order.

Parameters

Response

No response supported

Example Code

<?php
add_hook('FraudCheckPassed', 1, function($vars) {
    // Perform hook code here...
});

FraudOrder

Runs when an order is requested to be set as fraud, prior to the change of status actually occurring.

Parameters

Response

No response supported

Example Code

<?php
add_hook('FraudOrder', 1, function($vars) {
    // Perform hook code here...
});

OrderAddonPricingOverride

Executes as an addon price is being calculated in the cart.

Parameters

Response

Addon pricing can be overridden. Accepts a return of the keys ‘setup’ and ‘recurring’.

Example Code

<?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;
});

OrderDomainPricingOverride

Executes as a domain price is being calculated in the cart.

Parameters

Response

A float to override the first payment, or an array to override first and/or recurring amounts

Example Code

<?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];
});

OrderPaid

Executes when the first invoice for a new order is marked paid. This will execute in addition to the regular invoice payment hooks.

Parameters

Response

No response supported

Example Code

<?php
add_hook('OrderPaid', 1, function($vars) {
    // Perform hook code here...
});

OrderProductPricingOverride

Executes as a product price is being calculated in the cart.

Parameters

Response

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);

Example Code

<?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;
});

OrderProductUpgradeOverride

Executes as a product upgrade order is being calculated.

Parameters

Response

Return any key -> value pairs of the parameters to override. eg return array(‘discount’ => 10.00,);

Example Code

<?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;
});

OverrideOrderNumberGeneration

Executes prior to checkout. All cart information is passed to the hook.

Parameters

Response

Return the custom order number to be used (must be a valid numeric value).

Example Code

<?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();
});

PendingOrder

Runs when an order is requested to be set back to pending, prior to the change of status actually occurring.

Parameters

Response

No response supported

Example Code

<?php
add_hook('PendingOrder', 1, function($vars) {
    // Perform hook code here...
});

PreCalculateCartTotals

Executes as the cart totals are being calculated. All cart information is passed to the hook. Examples given here.

Parameters

Response

No response supported

Example Code

<?php
add_hook('PreCalculateCartTotals', 1, function($vars) {
    // Perform hook code here...
});

PreFraudCheck

Parameters

Response

No response supported

Example Code

<?php
add_hook('PreFraudCheck', 1, function($vars) {
    // Perform hook code here...
});

PreShoppingCartCheckout

Executes prior to checkout. All cart information is passed to the hook.

Parameters

Response

No response supported

Example Code

<?php
add_hook('PreShoppingCartCheckout', 1, function($vars) {
    // Perform hook code here...
});

RunFraudCheck

Executes as the fraud module is being checked for an order.

Parameters

Response

Return any value to skip the fraud check

Example Code

<?php
add_hook('RunFraudCheck', 1, function($vars) {
    // Perform hook code here...
});

ShoppingCartCheckoutCompletePage

Executes when the Complete Page is displayed on checkout.

Parameters

Response

Return HTML to be displayed on the order complete page.

Example Code

<?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" />';
});

ShoppingCartValidateCheckout

Executes during checkout completion, which occurs before order and invoice creation. Use this to prevent order creation and present errors to the user.

Parameters

Response

Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.

Example Code

<?php

add_hook('ShoppingCartValidateCheckout', 1, function($vars) {
    return [
        'Error message feedback error 1',
        'Error message feedback error 2',
    ];
});

ShoppingCartValidateDomain

Executes when Domain Update is occurring

Parameters

Response

Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.

Example Code

<?php

add_hook('ShoppingCartValidateDomain', 1, function($vars) {
    return [
        'Error message feedback error 1',
        'Error message feedback error 2',
    ];
});

ShoppingCartValidateDomainsConfig

Executes when Domain Update is occurring

Parameters

Response

Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.

Example Code

<?php

add_hook('ShoppingCartValidateDomainsConfig', 1, function($vars) {
    return [
        'Error message feedback error 1',
        'Error message feedback error 2',
    ];
});

ShoppingCartValidateProductUpdate

Executes when Product Update is occurring

Parameters

Response

Return accepts both a string or an array. Use a string for single error message or an array of strings for multiple error messages.

Example Code

<?php

add_hook('ShoppingCartValidateProductUpdate', 1, function($vars) {
    return [
        'Error message feedback error 1',
        'Error message feedback error 2',
    ];
});