# Partner Programme Hooks

https://dev.wisecp.com/es/affiliate-hooks

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 PHP

```php
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_typestring`sale` 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 PHP

```php
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 PHP

```php
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 PHP

```php
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.

## Related Articles

- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)