Affiliates – API

The information on this page is outdated. Please refer to the Documentation..

Please note that there are API functions which have not yet been documented here. This section will be updated periodically. Where in doubt, please use the code as a reference directly, it’s commented.

Requesting referrals

affiliates_suggest_referral( $post_id, $description = ”, $data = null, $amount = null, $currency_id = null, $status = null )

Suggest to record a referral. This function is used to actually store referrals and associated information.

Parameters:

• int $post_id the referral post id; where the transaction or referral originates
• string $description the referral description
• string|array $data additional information that should be stored along with the referral
• string $amount the referral amount, e.g. commission credited to the affiliate for the referral, if an $amount is given, the $currency_id is required an vice-versa.
• string $currency_id currency id (three upper case letters, e.g. USD, EUR, … )
• string $status referral status, must be one of AFFILIATES_REFERRAL_STATUS_ACCEPTED, AFFILIATES_REFERRAL_STATUS_CLOSED, AFFILIATES_REFERRAL_STATUS_PENDING, AFFILIATES_REFERRAL_STATUS_REJECTED

Returns:

– affiliate id if a valid referral is recorded, otherwise false

If a valid affiliate is found, the referral is stored and attributed to the affiliate and the affiliate’s id is returned.
Use the $description to describe the nature of the referral and the associated transaction.
Use $data to store transaction data or additional information as needed.

$data must either be a string or an array. If given as an array, it is assumed that one provides
field data (for example: customer id, transaction id, customer name, …) and for each field
one entry is added to the $data array obeying this format:

$data['example'] = array(
	'title' => 'Field title',
	'domain' => 'Domain',
	'value' => 'Field value'
);

This information is then used to display field data for each referral in the Referrals section.

– ‘title’ is the field’s title, the title is translated using the ‘domain’
– ‘value’ is displayed as the field’s value

Example:

A customer has submitted an order and a possible referral shall be recorded, including the customer’s id and the order id:

$data = array(
	'customer-id' => array( 'title' => 'Customer Id', 'domain' => 'my_order_plugin', 'value' => $customer_id ),
	'order-id'    => array( 'title' => 'Order Id', 'domain' => 'my_order_plugin', 'value' => $order_id )
);
if ( $affiliate_id = affiliates_suggest_referral( $post_id, "Referral for order number $order_id", $data ) ) {
	$affiliate = affiliates_get_affiliate( $affiliate_id );
	$affiliate_email = $affiliate['email'];
	if ( !empty( $affiliate_email ) ) {
		$message = "Dear Affiliate, an order has been made. You will be credited as soon as payment is received.";
		my_order_plugin_send_an_email( $affiliate_email, $message );
	}
}