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.


  • 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, … )


– 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


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 );

42 Responses to Affiliates – API

  1. andy January 27, 2014 at 8:41 am #


  2. andy January 25, 2014 at 1:29 pm #

    what code should i put in my wp page?
    so when it triggered it will count as a sale
    from certain affiliate

    • antonio January 27, 2014 at 7:33 am #

      What exactly do you need? I do not understand, when you want to register a commission, on page load?

      • andy January 27, 2014 at 7:44 am #

        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
        then this customer click buy page and go through

        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

        • antonio January 27, 2014 at 8:12 am #

          this page can help you.
          And you can use this plugin as reference.

  3. MoBizMa December 30, 2012 at 2:13 am #

    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.


    • kento December 30, 2012 at 5:40 pm #

      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.

  4. Bjorn-Arild Woll September 14, 2012 at 5:59 pm #


    Is it possible to translate the published names for the formfields from english to norwegian for me? Where should I do that if possible?


    • kento September 18, 2012 at 9:28 am #

      Yes you can translate these, a Norwegian translation file would have to be added. Do you know how to translate a plugin?

  5. iNovve July 19, 2012 at 8:27 pm #

    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…. ๐Ÿ™

    • iNovve July 19, 2012 at 8:56 pm #


      is this it?

      • iNovve July 19, 2012 at 10:28 pm #

        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….

        • kento July 20, 2012 at 12:57 pm #

          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.

          • iNovve July 20, 2012 at 2:50 pm #

            where do I implement custom method?

            affiliates-woocommerce-light.php or new file?

            if new file where?

            affiliates or affiliates-woocommerce-light folder?


      • kento July 20, 2012 at 1:04 pm #

        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.

  6. iNovve July 18, 2012 at 5:37 pm #

    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….

    • iNovve July 18, 2012 at 5:48 pm #

      $amount = round( floatval( $referral_rate ) * floatval( $order_subtotal ), AFFILIATES_REFERRAL_AMOUNT_DECIMALS );

      it’shere I need to change code?

    • kento July 19, 2012 at 7:15 pm #

      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.

  7. iNovve July 18, 2012 at 5:29 pm #


    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?

  8. Gil July 10, 2012 at 5:14 am #

    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?

    • kento July 10, 2012 at 1:17 pm #

      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.

  9. Garn Penrod July 9, 2012 at 1:13 am #

    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.

    • kento July 10, 2012 at 1:14 pm #

      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 ๐Ÿ˜‰

  10. Rohit Manglik June 24, 2012 at 11:44 am #

    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

  11. Bjallen April 26, 2012 at 6:04 pm #

    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!


  12. bj allen April 26, 2012 at 3:18 am #

    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, but it was over my head as well.


    • kento April 26, 2012 at 9:17 am #

      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.php and you could use that example to adapt your form. If you are using Contact Form 7, then there is an integration for that.

  13. Max November 8, 2011 at 3:53 pm #

    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.


    (Oh, and I forgot to enter the captcha just now and I lost this whole comment, so I had to type it again)

    • kento November 8, 2011 at 5:33 pm #

      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.

      • Max November 10, 2011 at 1:26 am #

        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”.



        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?

        • kento November 10, 2011 at 10:52 am #

          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.

        • Jafar June 16, 2012 at 7:22 pm #

          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!

  14. Max November 8, 2011 at 3:23 pm #

    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,


    • kento November 8, 2011 at 3:32 pm #

      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.

  15. Dice August 6, 2011 at 6:49 pm #

    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 …


    • kento August 8, 2011 at 9:45 am #

      It’s the text domain used for translation, see e.g.

      Cheers ๐Ÿ™‚

      • Dice August 8, 2011 at 6:13 pm #

        Could you give a use case example?

        I don’t quite get it yet ๐Ÿ™‚

        • kento August 8, 2011 at 7:39 pm #

          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.

          • Dice August 13, 2011 at 10:28 am #

            Now it’s clear. Thanks!

We use cookies to optimize your experience on our site and assume you're OK with that if you stay.
OK, hide this message.

Affiliates ยท Contact ยท Jobs ยท Terms & Conditions ยท Privacy Policy ยท Documentation ยท Downloads ยท Useful Plugins ยท My Account