REST API Extended – Managing Affiliates

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 affiliates on top of the two read-only endpoints already available in AffiliateWP core.

All five endpoints leverage the same two route patterns:

  1. affiliates – When sent a GET request, a list of affiliates are returned and can be filtered with additional arguments. When sent a POST or PUT request, a new affiliate can be created.
  2. affiliates/[ID] – When sent a GET, PATCH, or DELETE request, a single affiliate 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.

Whether you're planning to read, write, edit, or delete affiliates, this add-on makes it possible.

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 an Affiliate

Affiliates can be created by sending a POST or PUT request to the affiliates route:

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

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

  • user_id – (integer) Every affiliate shares a 1:1 relationship with an existing WordPress user account. If no suitable user ID is available, the create_user argument can be passed to try creating an affiliate and a user account in the same step.
  • username – (string) Optional. Used to set the user_login when creating a new user account. If not provided, the payment_email will be used to generate the user_login of the generated WordPress user.
  • create_user – (boolean)  Used to create a new user account, in lieu of user_id. Must be accompanied by a unique payment_email value, which is used when registering the user account.
  • rate – (integer) Affiliate rate to use. If not specified, the global default will be used.
  • rate_type – (string) Rate type. Default accepted types are'percentage' or 'flat'. If not specified, the global default will be used.
  • payment_email – (string) Affiliate payment email. If omitted, the user account email will be used on retrieval. Required when using create_user.
  • status – (string) Affiliate status. Accepts 'active', 'inactive', 'pending', or 'rejected'. Default is 'pending'.
  • notes – (string) Affiliate notes.

Creating an affiliate with user_id:

Method: PUT/POST
Endpoint: https://example.com/wp-json/affwp/v1/affiliates/?user_id=5&rate=25&rate_type=percentage

The new affiliate would be associated with user_id 5 and given a commission rate of 25 percent.

Example response:

{
  "affiliate_id": 30,
  "user_id": 5,
  "rate": "25",
  "rate_type": "percentage",
  "payment_email": "",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2017-01-26 07:27:52",
  "id": 30
}

Creating an affiliate and a user with create_user:

Method: PUT/POST
Endpoint: https://example.com/wp-json/affwp/v1/affiliates/?create_user=1&payment_email=getsome@rest.dev

The new affiliate would be associated with the new user (ID 10) and given a payment email of getsome@rest.dev.

Example response:

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "getsome@rest.dev",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2017-01-26 07:27:52",
  "id": 31
}

Editing an Existing Affiliate

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

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

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

  • account_email – (string) New account email for the associated user account.
  • payment_email – (string) New payment email.
  • rate – (integer) Affiliate rate to use
  • rate_type – (string) Rate type.
  • status – (string) Affiliate status. Accepts 'active', 'inactive', 'pending', or 'rejected'.
  • notes – (string) Affiliate notes.

Updating an Affiliate

In this example, we'll update an affiliate's status from pending to active.

Method: POST/PATCH
Endpoint: https://example.com/wp-json/affwp/v1/affiliates/31?status=active

Response:

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "getsome@rest.dev",
  "status": "active",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2017-01-26 07:27:52",
  "id": 31
}

Deleting an Affiliate

An affiliate can be deleted by sending a DELETE request to the affiliates/[id] route:

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

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

Example request:

Method: DELETE
Endpoint: https://example.com/wp-json/affwp/v1/affiliates/31

Response:

{
  "deleted": true,
  "previous": {
    "affiliate_id": 31,
    "user_id": 10,
    "rate": "",
    "rate_type": "",
    "payment_email": "getsome@rest.dev",
    "status": "active",
    "earnings": 0,
    "unpaid_earnings": 0,
    "referrals": 0,
    "visits": 0,
    "date_registered": "2017-01-26 07:27:52",
    "id": 31
  }
}