REST API Extended – Managing Payouts

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

All five endpoints leverage the same two route patterns:

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

Payouts can be created by sending a POST or PUT request to the payouts route:

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

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

  • affiliate_id – (integer) ID of the affiliate to associate the payout with. This field is required.
  • referrals – (array|string) Array or comma-separated list of referral IDs to include in the payout.
  • amount – (float) Payout amount (typically derived from referral amounts).
  • payout_method – (string) Payout method.
  • status – (string) Accepts 'paid' or 'failed'. Default 'paid'.

Creating a payout:

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

The new payout, with payout_id 15 would cover referrals 10, 15, and 20 for affiliate_id 30.

Example response:

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 27.87,
  "payout_method": "manual",
  "status": "paid",
  "date": "2017-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Editing an Existing Payout

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

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

The edit endpoint accepts any of the following arguments:

  • affiliate_id – (integer) ID of the affiliate to associate the payout with. This field is required.
  • referrals – (array|string) Array or comma-separated list of referral IDs to include in the payout.
  • amount – (float) Payout amount (typically derived from referral amounts).
  • payout_method – (string) Payout method.
  • status – (string) Accepts 'paid' or 'failed'. Default 'paid'.

Updating a Payout

In this example, we'll update a payout's status from failed to paid.

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

Response:

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 30,
  "payout_method": "manual",
  "status": "paid",
  "date": "2017-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Deleting a Payout

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

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

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

Example request:

Method: DELETE
Endpoint: https://example.com/wp-json/affwp/v1/payouts/15

Response:

{
  "deleted": true,
  "previous": {
    "payout_id": 6751,
    "affiliate_id": 5454,
    "referrals": "35878,35877,35876",
    "amount": 30,
    "payout_method": "manual",
    "status": "paid",
    "date": "2017-01-26 12:55:13",
    "owner": 1,
    "id": 6751
  }
}

Related Articles