Referrals

`Affiliates_Referral_WordPress`

The Affiliates_Referral_WordPress class provides methods that allow to record referrals.

`evaluate()`

Referral evaluation method. This will create a new referral if an affiliate is creditable.

A referral is recorded for an affiliate if the system decides it is appropriate. This is the normal way to record referrals with Affiliates Pro and Enterprise.

Parameters

int $post_id (required)
string $description (optional) default: ”
array $data (optional) default: null
string $base_amount (optional) default: null
string $amount (optional) default: null
string $currency_id (optional) default: null
string $status (optional) default: null
string $type (optional) default: null
boolean $test (optional) default: false, if set to true no referral will be recorded

Usage:

$r = new Affiliates_Referral_WordPress(); $r->evaluate( $post_id, $description, $data, $base_amount, $amount, $currency_id, $status, $type, $reference, $test );

`add_referrals()`

Referral recording method. This will record new referrals.
Referrals are recorded for each affiliate specified. Note that the affiliate(s) to be credited with referrals must be specified explicitly, the system will not choose the affiliates as opposed to the evaluate method.

Parameters

array $affiliate_ids (required)
int $post_id (required)
string $description (optional) default: ”
array $data (optional) default: null
string $base_amount (optional) default: null
string $amount (optional) default: null
string $currency_id (optional) default: null
string $status (optional) default: null
string $type (optional) default: null
boolean $test (optional) default: false, if set to true no referral will be recorded

Usage:

$r = new Affiliates_Referral_WordPress(); $r->add_referrals( $affiliate_ids, $post_id, $description, $data, $base_amount, $amount, $currency_id, $status, $type, $reference, $test );

Example

This is an example of how to suggest recording a referral and let the system decide whether it should credit an affiliate.

        // net order amount
        // the commission is calculated based on that
        $net_amount = 100;

        // appropriate currency code for the referral
        $currency = 'USD';

        // related post ID, order ID, ...
        $post_id = $order_id;

        $data = array(
            'order_id' => array(
                'title'  => 'Order #',
                'domain' => 'affiliates',
                'value'  => esc_sql( $order_id )
            ),
            'order_total' => array(
                'title'  => 'Total',
                'domain' =>  'affiliates',
                'value'  => esc_sql( $net_amount )
            ),
            'order_currency' => array(
                'title'  => 'Currency',
                'domain' =>  'affiliates',
                'value'  => esc_sql( $currency )
            )
        );

        $r = new Affiliates_Referral_WordPress();
        $description = sprintf( 'Order #%s', $order_id );
        $r->evaluate(
            $post_id,
            $description,
            $data,
            $net_amount,
            null,
            $currency,
            null,
            'sale'
        );

Useful related Actions and Filters

Once a referral has been recorded, the affiliates_referral action is triggered and this can be used for post-processing. In the following example, we make an adjustment after a referral is recorded if we detect a specific product ID and we then update the referral.

add_action( 'affiliates_referral', 'my_affiliates_referral', 10, 2 );
function my_affiliates_referral( $referral_id, $data ) {
    $referral = new Affiliates_Referral();
    if ( $referral->read( $referral_id ) ) {
        // $referral->reference contains the order ID
        if ( $referral->referral_items !== null ) {
            foreach ( $referral->referral_items as $item ) {
                // $item->reference contains the order item ID
                if ( $item->type === 'product' ) {
                    $product_id = $item->object_id;
                    if ( $product_id === 123 ) {
                        error_log(
                            'Item amount is ' . $item->amount . ' ... reducing by 1'
                        );
                        $item->amount -= 1;
                    }                    
                }
            }
            $referral->compute(); // calculates the total
            $referral->update(); // persists the changes
        }
    }
}

Please note that the above example is just to illustrate how you can work with the referral object and its items.

For adjustments in commission calculations, we recommend to use formula-based rates. These allow to calculate the commissions based on the current transaction context and before the actual referral is recorded and the affiliates_referral action is triggered.

The affiliates_formula_computer_variables filter can be used more appropriately to fine-tune calculated commissions. It can modify or provide additional variables that can then be used in the rate’s formula, to calculate the actual commission amount for each referral item.

Primary

Navigation