Your cart is currently empty!
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 );
}
}
Comments
42 responses to “Affiliates – API”
thanks!
what code should i put in my wp page?
so when it triggered it will count as a sale
from certain affiliate
Hi,
What exactly do you need? I do not understand, when you want to register a commission, on page load?
cheers
i mean there’s must be a code triggered when an affiliate makes a sale, what is this code? and this code must be put somewhere inside a wordpress page
example: a customer hit http://www.website.com?id=aff1
then this customer click buy page and go through http://www.website.com/buy.php?id=aff1
this buy.php page should be a code triggered inside it to confirm a sale made by affiliate named aff1.. thi is the code i’m looking for
Hi,
this page can help you.
And you can use this plugin as reference.
cheers
Hi Kento,
How can your nice plugin be used in conjunction with taking orders by phone?
We’d like to be able to offer an affiliate program for our site, however, sales will be likely mostly over the phone.
Thanks,
Eileen
Hi Eileen,
You will be able to record referrals manually with the next version coming up, which I assume would be appropriate for the process you are trying to implement.
Cheers
Hi,
Is it possible to translate the published names for the formfields from english to norwegian for me? Where should I do that if possible?
B-A
Yes you can translate these, a Norwegian translation file would have to be added. Do you know how to translate a plugin?
Thank you for your comment.
My only doubt right now is how to access to a custom field created in the product… I have no idea how to retrieve its data…. 🙁
$product_custom_fields;
is this it?
but this would mean I have to access to the products in the order…
so in the function
public static function woocommerce_checkout_order_processed( $order_id ) {
I must add some code to pull the products present in the order, then I go through the products to return each commission…..
I think that’s it, but have no idea how to do it….
When you implement the custom method following the example, you get the order ID in $parameters[‘post_id’].
Then you can use
$order = new woocommerce_order();if ( $order->get_order( $parameters['post_id'] ) ) {
// work with the order, e.g. iterate over its products
}
in the custom method to calculate the referral amount by product using the product’s meta.
where do I implement custom method?
affiliates-woocommerce-light.php or new file?
if new file where?
affiliates or affiliates-woocommerce-light folder?
cheers
You can just take the example plugin and modify it to do the calculation. You can download it on this page http://www.itthinx.com/documentation/affiliates/api/examples/
If you use
WC_Product:$product = new WC_Product( $product_id );you can get the custom fields with$product->product_custom_fields, I’d say that should then make it easy for you to finish the custom method.How can I use string $amount to check a custom field in woocommerce. I would define a custom fild comission in woocommerce products. then when checking for comission I would check that field and override comission percentage in Affiliates and use that field instead….. I think this is the best way to do it…. but how? I’m a bit lost….
$amount = round( floatval( $referral_rate ) * floatval( $order_subtotal ), AFFILIATES_REFERRAL_AMOUNT_DECIMALS );
it’shere I need to change code?
That approach looks right. You can use a custom method (see the example on how to implement one) to read the custom field for each product in an order and calculate the referral amount as desired.
Hi
I really need urgently that I’m able to define different commissions for different products. I’m using woocommerce. I need a way to define that for each product the comission to pay….
Any idea where should I start?
same exact issue as poster above (Garn Penrod). I use Paypal for checkout and want to have Affiliates track the referrals once payment is done. I think these codes go in some file (plugin PHP file?), not in WP page’s html section as Garn suggests, but not even sure about that… is there a basic tutorial to get this working for WP/programming rookies?
The same comment applies here.
Honestly, doing a PayPal integration is not a job for programming rookies but for expert Software Engineers. Trying to do things like that without the expertise is like operating your own knee without even being a surgeon.
I am trying SOOO hard to get this working. I am trying to have affiliates API recommend a referral after the client completes the checkout and arrives at the confirmation page. I don’t know much about how to read the call here. If I could get help with that, I think I’ll be fine. I figured out the rest pretty easily, but this suggest referral code is kicking my butt! And one more thing. If I understood correctly, all I would have to do is copy and paste the correctly prepared code above to the confirmation page’s html section and it should work, right? Or am I misunderstanding this altogether? Thank you for your great plugins! I’m just stuck on this one piece.
I see that you are using PayPal for checkout, if you are using your own framework to control the checkout process and capture the IPN then you can build what you need by deriving from any of the free integrations: these use the affiliates_suggest_referral function. If you do not have IPN capture in place then you’d be better off getting the Affiliates Pro integration for PayPal – the amount of work involved in recreating the integration with PayPal wouldn’t justify the cost of getting the plugin, unless you work for less than $1 per hour 😉
Does this API work on WordPress v3.4?
I copied the example code mentioned above it is showing following error
Fatal error: Call to undefined function wp_get_current_user() in /hermes/waloraweb068/b592/moo.oprotechcom/careerbreeder/wp-content/plugins/affiliates/lib/core/wp-init.php on line 785
You’re trying to use a function too early. See for example: http://stackoverflow.com/questions/6127559/wordpress-plugin-call-to-undefined-function-wp-get-current-user
It’s working now.. thanks 🙂
I am using the Easy Contact Forms plugin now, but I am more than willing to switch to Contact Form 7 if that would make it easier. I will take a look at the integration and see if I can make it work. Thanks for your help!
BJ
I installed the plugin and got it working successfully, but this API piece is way over my head. I have a simple order form on my site, and I want to generate a referral when the form is submitted.
Does anyone have any suggestions on where I can go for guidance to learn how to implement this API? I tried reading the developer’s docs on WordPress.org, but it was over my head as well.
Thanks!!
Do you use a plugin to generate the form or is it a template? There is an example widget (Affiliates Contact), that is handled in
affiliates/lib/core/class-affiliates-contact.phpand you could use that example to adapt your form. If you are using Contact Form 7, then there is an integration for that.Hello Kento,
Thanks for the quick reply. It still leaves a few questions.
How does WordPress know who is the affiliate on the confirmation page? Can I just use $post_id without adding other code?
How can I add the amount spent to the database? We want to pay our affiliates a percentage of what we make through them, so it is important to save this.
Chao
(Oh, and I forgot to enter the captcha just now and I lost this whole comment, so I had to type it again)
WordPress doesn’t know about affiliates, Affiliates does. When you suggest a referral through the API, Affiliates will check to see if an affiliate can be credited.
Parameters with default values can be omitted, so yes you could just pass $post_id.
You can store the sales amount along with the $data and can pass the calculated commission as $amount (must give $currency_id as well). The amount will appear in the referral.
Alright, looks like I got it working 🙂
I will post my code here, maybe someone else can benefit from it. And then at the bottom there is another question.
The code looks like this now:
affiliates_suggest_referral( get_the_ID(), $transaction_id, null, calculate_amount(), “EUR”, “AFFILIATES_REFERRAL_STATUS_ACCEPTED” );
So I use get_the_ID() to get the post id. This is actually always the same page, so it does not say anything relevant.
for the description I use my shopping cart’s transaction_id. This way I can connect the affiliate referral to the rest of the transactions in the system.
Data is empty. I do not know what kind of information I would like to pass on.
calculate_amount() gives me the amount of the payment minus shipping costs, since affiliates are only getting paid for products we sell through them.
The only amount you can pay in is euro’s, so “EUR”.
And the status is: AFFILIATES_REFERRAL_STATUS_ACCEPTED
—-
If I save the referral with status AFFILIATES_REFERRAL_STATUS_PENDING somewhere else, can I then update the status after the payment is done? How will Affiliates know that I am updating another referral and not adding a new one?
Thanks for sharing your solution Max 🙂
One thing though, you should remove the double quotes around AFFILIATES_REFERRAL_STATUS_ACCEPTED as this is a named constant.
And a suggestion: You could store the transaction ID in $data along with a link to the actual order.
About your question regarding AFFILIATES_REFERRAL_STATUS_PENDING: yes you can update the status directly from Affiliates > Referrals – there is a Set button in the Status column for each referral.
Hi Max, Can you please inform me on where you placed the affiliates_suggest_referrral( code?? I’m having a hard time figuring that out. Thanks in advance!
Hello Kento,
Your plugin looks super and I really want to implement it. I am looking for how I can let the system know that a payment has been made. I am not using any of the ecommerce plugins, but a simple iDeal button (dutch bank payment system). Is there a call to the API I can place somewhere on the page where the payment is validated.
Thank you,
Max
Thanks Max, love to hear you like it 🙂
Once you get confirmation from iDeal you can call the API to suggest the referral. E.g. if you have a URL that your payment gateway visits to confirm payment, you can place the API call there.
Cheers
Hey kento,
What is the ‘domain’ property used for?
I am unable to find any reference to it in the backend – might be missing it somehow …
Cheers,
Dice
It’s the text domain used for translation, see e.g. http://codex.wordpress.org/I18n_for_WordPress_Developers
Cheers 🙂
Could you give a use case example?
I don’t quite get it yet 🙂
Sure, actually this post comes in handy: Recording sign-up referrals.
You can download a complementary plugin from there which stores additional data in ‘user-name’ … the title of that field is ‘Username’ and the text-domain used for translating that title is ‘affiliates-members’ … the domain of that plugin.
The text-domain is used in distinguishing text for translation from one domain to another, giving the possibility of different translations of the same term in different domains.
Now it’s clear. Thanks!