Partner Programme Hooks

1 views Markdown

The four hooks over enrolment, commissions, referral clicks and payout requests.

Overview

The four moments of the partner programme: a customer joins, their link is clicked, a sale raises a commission, and they ask to be paid.

One distinction to hold from the start: the id of the partner record and the id of the customer are separate numbers, and the hooks carry both.

Reference

Following an enrolment

actionuser.affiliate_activated

ClientAffiliate at enrolment

Runs after a customer joins the partner programme.

Parameters 2

$user_idintThe id of the account that joined.

$aff_idintThe id of the partner record created. This is a different number from the customer id; the sibling hooks carry both separately.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.affiliate_activated', 10, function ($user_id, $aff_id) {
    // Two different ids: the partner record is not the customer number.
    Acme::openPartnerDashboard($user_id, $aff_id);
});

Following a commission being made

actionuser.affiliate_commission_created

ClientAffiliate sale and renewal

Runs after a commission is credited to a partner. Both first sales and renewals land here.

Parameters 4

$affiliate_idintThe partner record receiving it.

$servicearrayThe service behind it: amount, currency and owner.

$transaction_typestringsale for a first sale, renewal for a renewal. On renewals the commission recurs every period: mind the difference if you hand out a one-off reward.

$commissionfloatThe commission worked out.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.affiliate_commission_created', 10,
    function ($affiliate_id, $service, $transaction_type, $commission) {
        // On renewals the commission recurs every period.
        if ($transaction_type === 'sale') Acme::rewardFirstSale($affiliate_id);
    });

Following a referral click

actionuser.affiliate_referral_clicked

ClientAffiliate on every click

Runs when a partner link is clicked. It fires on every click, with or without a sale, with or without a logged-in visitor.

Parameters 2

$ownerIdintThe customer id of the partner; this is the attribution key.

$contextarrayThe click context: the partner record, where the visitor came from and their address. The referring address can be empty, and it may count as personal data, so mind how long you keep it.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.affiliate_referral_clicked', 10, function ($ownerId, $context) {
    // It runs on every click: keep heavy work out of here.
    Acme::countClick($ownerId);
});

Following a payout request

actionuser.affiliate_withdrawal_requested

ClientAffiliate nothing paid yet

Runs when a partner asks for their earnings. Nothing has been paid: the record opens in a waiting state.

Parameters 6

$uidintThe customer asking.

$affIdintThe partner record, not the customer id.

$amountfloatThe amount asked for; it matches what was written exactly.

$cidintThe currency of the partner.

$gatewaystringThe payout channel chosen.

$widintThe request record created; always above zero.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.affiliate_withdrawal_requested', 10,
    function ($uid, $affId, $amount, $cid, $gateway, $wid) {
        // Nothing was PAID: the request opened in a waiting state.
        Acme::queuePayout($wid, $affId, $amount, $gateway);
    });

Pitfalls

The partner record and the customer are separate numbers

The payout hook carries both the customer id and the partner record, and they are not the same number. Taking the partner record for a customer id books the earnings against the wrong account.

On renewals the commission recurs every period

The commission hook fires on the first sale and on every renewal. If you hand out a one-off reward, check the transaction type; otherwise the same customer earns it again each month.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Overview

Reference

Following an enrolment

Following a commission being made

Following a referral click

Following a payout request

Pitfalls

Related Articles