REST API Extended – Managing Referrals

Note: This article relates to the REST API Extended pro add-on.

REST API Extended adds three endpoints, one each for creating, editing, and deleting referrals on top of the two read-only endpoints already available in AffiliateWP core.

All five endpoints leverage the same two route patterns:

1. referrals – When sent a GET request, a list of referrals are returned and can be filtered with additional arguments. When sent a POST or PUT request, a new referral can be created.
2. referrals/[id] – When sent a GET, PATCH, or DELETE request, a single referral can be retrieved, edited, or deleted, respectively.

Both routes can also accept generic OPTIONS requests, which can be very helpful for discovering information about available endpoints, accepted request types and arguments, and item schema.

All requests must be authenticated using API keys, which are generated and managed via the Affiliates → Tools → API Keys tab. Check out the REST API - Authentication article for more information.

Creating a Referral

Referrals can be created by sending a POST or PUT request to the referrals route:

https://example.com/wp-json/affwp/v1/referrals

The create endpoint accepts any of the following affwp_add_referral() arguments:

• affiliate_id – (integer) ID of the affiliate to associate the referral with. This field is required. See user_id and user_name.
• user_id – (integer) User ID used to retrieve the associated affiliate ID if affiliate_id is not sent.
• user_name – (string) Username used to retrieve the associated affiliate ID if affiliate_id is not sent.
• amount – (float) Referral amount. 
  
  Note: this is the final referral amount after the referral rate calculations have been applied.
  
  
• currency – (string) Referral amount currency.
• description – (string) Referral description.
• reference – (string) Referral reference. Usually this contains product information such as product IDs.
• context – (string) Context under which the referral was created. Usually this is the integration slug.
• status – (string) Accepts 'paid', 'unpaid', 'pending', or 'rejected'. Default 'pending'.

Creating a referral:

Method: PUT/POST
Endpoint: https://example.com/wp-json/affwp/v1/referrals/?affilite_id=30&amount=15

The above would create a new referral associated with affiliate ID 30 at an amount of $15 with status 'pending'.

Example response:

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "pending",
  "amount": "15.00",
  "currency": "USD",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2017-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Editing an Existing Referral

Single referrals can be updated by sending a POST or PATCH request to the referrals/[id] route:

https://example.com/wp-json/affwp/v1/referrals/[id]

The edit endpoint accepts any of the following affwp_process_update_referral() arguments:

• affiliate_id – (integer) ID of the affiliate to associate the referral with.
• visit_id – (integer) ID of the visit to associate the referral with.
• amount – (float) Updated referral amount.
• currency – (string) Updated referral amount currency.
• description – (string) Updated referral description.
• reference – (string) Referral reference. Usually this contains product information such as product IDs.
• context – (string) Context under which the referral was created. Usually this is the integration slug.
• status – (string) Accepts 'paid', 'unpaid', 'pending', or 'rejected'.

Updating a Referral

In this example, we'll update a referral's status from  pending to paid.

Method: POST/PATCH
Endpoint: https://example.com/wp-json/affwp/v1/referrals/450?status=paid

Response:

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "paid",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2017-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Deleting a Referral

A referral can be deleted by sending a DELETE request to the referrals/[id] route:

https://example.com/wp-json/affwp/v1/referrals/[id]

The delete endpoint accepts no additional arguments. When a referral as been successfully deleted, a key/value pair of deleted: true will be included in the response, along with a copy of the old referral response.

Example request:

Method: DELETE
Endpoint: https://example.com/wp-json/affwp/v1/referrals/450

Response:

{ 
  "deleted": true, 
  "previous": {
    "referral_id": 35879, 
    "affiliate_id": 5454, 
    "visit_id": 0, 
    "description": "", 
    "status": "paid", 
    "amount": "", 
    "currency": "", 
    "custom": "", 
    "context": "", 
    "campaign": "", 
    "reference": "", 
    "products": "", 
    "date": "2017-01-26 22:28:54", 
    "payout_id": "0", 
    "id": 35879
  }
}