Custom WHMCS hooks for an affiliate integration

We had to extend a WHMCS-based web shop so that it sends data about purchases to an external affiliate (partner programme) system. The affiliate system calculates the partners’ commission from this data, so it was important that no purchase got lost and none was counted twice.

Starting point

The affiliate system mainly offered JavaScript tracking codes, which would have had to be inserted into the page shown after the order. This had two problems:

  • Browser-based tracking is often blocked by ad and tracking blockers, so some of the purchases would never have reached the affiliate system.
  • Not only the order but also the payment had to be reported. The two don’t necessarily happen at the same time: with a bank transfer, the payment can arrive days later, when the customer is no longer on the site and there is no browser to run the code.

Fortunately, it turned out that the affiliate system also had an API. So the report could be sent reliably by the WHMCS server instead of the browser.

Solution: WHMCS hooks

At key points of its operation, WHMCS triggers events (hooks) that your own PHP code can subscribe to. Two events were needed:

  • AfterShoppingCartCheckout – when the customer places the order. This is when the cart contents, the amount and the customer’s email address have to be sent.
  • InvoicePaid – when the invoice for the order is paid. This is when we have to report that the purchase has also been paid for.

Hooks go into the includes/hooks directory of WHMCS, and WHMCS updates don’t overwrite them. A simplified skeleton:

<?php
// includes/hooks/affiliate.php (simplified example)

add_hook('AfterShoppingCartCheckout', 1, function (array $vars) {
    $order = localAPI('GetOrders', ['id' => $vars['OrderID']]);
    // assemble cart, amount and email address, then send to the affiliate API
});

add_hook('InvoicePaid', 1, function (array $vars) {
    $invoice = localAPI('GetInvoice', ['invoiceid' => $vars['invoiceid']]);
    // if the invoice belongs to an affiliate order: report the payment
});

The required data comes from the internal WHMCS API (localAPI), so the code doesn’t depend on the structure of the WHMCS database.

What to watch out for in an integration like this

  • Duplicate sends. In some cases the same invoice can be marked “paid” more than once (for example when a payment is reversed and then recorded again). It’s worth storing what has already been sent, and reporting it only once.
  • Timeouts. The hook runs during the checkout process. If the affiliate API responds slowly, the customer waits. You need a short timeout, and a failed API call must not block the order.
  • Logging. It’s worth logging every request and response (WHMCS provides the logModuleCall function for this), so that if a commission is disputed, you can look up what was sent.
  • Data protection. The customer’s email address is passed to a third party; this has to be covered in the privacy notice and in the data processing agreement.

Result

Purchases and payments reach the affiliate system from the WHMCS server, independently of the browser, including bank transfers that arrive late. The solution is built on the existing WHMCS hooks; the WHMCS source code didn’t have to be touched.

Looking back from 2026

The hook system still works this way today, and it’s the recommended way to extend WHMCS: your own code stays separate, and updates don’t overwrite it. Since then, we have also developed our own WHMCS modules to run aWh; we present them on the Software page. You can read about introducing and running WHMCS on the For hosting providers page.

Let’s talk about your project

Tell us briefly how we can help, and we will get back to you as soon as we can.

Get in touch