AffiliateWP Documentation

Documentation, Reference Materials, and Tutorials for AffiliateWP

REST API v1 Setup and Usage

How to Set Up and Use the REST API v1

AffiliateWP has a slew of read-only REST endpoints that build upon the infrastructure included with WordPress 4.4 and later.

In this article, we’ll show you how to set up and use the REST API v1 to access AffiliateWP Data.

REST API – Authentication

In order to leverage core REST endpoints, all API consumers must authenticate using API keys generated from a new API Keys tab located at Affiliates → Tools → API Keys.

The REST API uses  basic authentication with a combination of a Public Key and Token.

Before you can authenticate an API request, you need a set of API keys. These are user-specific and can be created in Affiliates → Tools → API Keys:

To generate a new set of API keys, enter the username of the user the keys should belong to and click Generate New API Keys.

Note: The user account the API keys are associated with must have the proper capabilities in order for the API to work. Typically this means the user needs to have the Administrator role. See our documentation on roles and capabilities for more information.

Once the API keys are created, you can authenticate with the REST API by including the keys in the authentication header. The Public Key should be passed as the user and the Token as the password.

For example, using Postman, our authenticated request would look like this:

If using curl, an authenticated request would look like this:

curl -u 229c1d4292800a4fdaa1099a4c646c9a:c7fd218923e058e1637698e5257855de http://local.wp/woo/wp-json/affwp/v1/affiliates

The authorization header must be included with every API request in order to properly authenticate with the API. If basic authentication is not provided or the credentials are incorrect, an error message will be returned: 

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": {
    "status": 403
  }
}

Routes and Endpoints

AffiliateWP offers five routes and multiple underlying endpoints. Those five routes are:

  1. Affiliates
  2. Creatives
  3. Payouts
  4. Referrals
  5. Visits

Click the route names above to find out more about their respective endpoints, see example requests, and more.

Note: complete Create, Read, Update, and Delete (CRUD) operations can be enabled through the REST API Extended add-on. See the REST API Extended documentation for information on Create, Update, and Delete operations.

1. Affiliate Endpoints

AffiliateWP core 1.9+ offers two, read-only REST endpoints for affiliates:

  1. affiliates – Retrieves response objects for all affiliates on the current site
  2. affiliates/{ID} – Retrieves a response object for an affiliate with the given affiliate ID

The affiliate endpoints can be accessed via GET requests at the following locations:

http://example.com/wp-json/affwp/v1/affiliates
http://example.com/wp-json/affwp/v1/affiliates/ID

All affiliate endpoints and their various options are also discoverable by visiting the AffiliateWP REST namespace directly:

http://example.com/wp-json/affwp/v1/
Endpoints

The affiliates endpoint accepts any valid get_affiliates() arguments:

  • number – The number of results to retrieve (if available)
  • offset – The number of results to offset in the query. Default is 0 (no offset)
  • affiliate_id – The affiliate ID or array of IDs to query for.
  • user_id – The user ID or array of IDs to query payouts for.
  • exclude – Affiliate ID or array of IDs to exclude from the request.
  • search – Terms to search for affiliates. Accepts an affiliate ID or a string.
  • status – The affiliate status. Accepts ‘active’, ‘inactive’, ‘pending’, or ‘rejected’.
  • order – How to order results. Accepts ‘ASC’ (ascending) or ‘DESC’ (descending).
  • orderby – Which field to order the response results by. Default is ‘date’
  • fields – Specific fields to return for each affiliate in the response. Default ‘*’ (all). Accepts ‘ids’ or any valid column

Additional arguments:

  • user – If user is passed as true, custom user objects will be retrieved on the fly for each affiliate in the response. Care should be taken when using this option due to the 1:1 increase in database queries associated with each affiliate
  • meta – If passed as true, an array of affiliate meta will be retrieved on the fly for each affiliate in the response. Just as with user, care should be taken due to the decreased performance impact.

All valid arguments can also be derived by sending an OPTIONS request to the either endpoint.

The affiliates/{ID} endpoint accepts any valid affiliate ID. Additionally, if user and/or meta are passed as true, a custom user object and/or array of affiliate meta will respectively be retrieved on the fly to include with the response.

Visibility

All endpoints require the API key and token except for the main affwp/v1 endpoint.

Response

Responses are returned in JSON form.

Example affiliates response:

[
  {
    "affiliate_id": 2736,
    "user_id": 1336,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "active",
    "earnings": 6,
    "unpaid_earnings": 0,
    "referrals": 6,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2736
  },
  {
    "affiliate_id": 2737,
    "user_id": 1337,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "inactive",
    "earnings": 1,
    "unpaid_earnings": 3145.59,
    "referrals": 1,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2737
  }
]

Example affiliates/{ID} response:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25"
}

Example affiliates{ID}?user=1 response:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "user": {
    "ID": "1337",
    "user_login": "user_1_11",
    "user_nicename": "user_1_11",
    "user_url": "",
    "user_registered": "2016-08-17 19:46:25",
    "user_status": "0",
    "display_name": "User 11",
    "spam": "0",
    "deleted": "0",
    "first_name": "",
    "last_name": ""
  }
}

Example affiliates{ID}?meta=1 response:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "active",
  "earnings": 32039.07,
  "unpaid_earnings": 3145.59,
  "referrals": 3192,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "meta": {
    "some_key": [
      "some_value"
    ]
  },
  "id": 2737
}<br>

.

2. Creatives Endpoints

AffiliateWP core 1.9+ offers two, read-only REST endpoints for creatives:

  1. creatives – Retrieves response objects for all creatives on the current site
  2. creatives/{ID} – Retrieves a response object for an creative with the given creative ID

The creative endpoints can be accessed via GET requests at the following locations:

http://example.com/wp-json/affwp/v1/creatives
http://example.com/wp-json/affwp/v1/creatives/ID

All creative endpoints and their various options are also discoverable by visiting the AffiliateWP REST namespace directly:

http://example.com/wp-json/affwp/v1/
Endpoints

The creatives endpoint accepts any valid get_creatives() arguments:

  • number – The number of results to retrieve (if available)
  • offset – The number of results to offset in the query. Default is 0 (no offset)
  • creative_id – The creative ID or array of IDs to query for.
  • status – The creative status. Accepts ‘active’ or ‘inactive’.
  • order – How to order results. Accepts ‘ASC’ (ascending) or ‘DESC’ (descending).
  • orderby – Creatives table column to order by.
  • fields – Specific fields to return for each creative in the response. Default ‘*’ (all). Accepts ‘ids’ or any valid column.

All valid arguments can also be derived by sending an OPTIONS request to the either endpoint.

The creatives/{ID} endpoint accepts any valid creative ID.

Visibility

All endpoints require the API key and token except for the main affwp/v1 endpoint.

Response

Responses are returned in JSON form.

Example creatives sresponse:

  {
    "creative_id": 2,
    "name": "My Other Creative",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "",
    "status": "inactive",
    "date": "2016-05-11 23:35:58",
    "id": 2
  },
  {
    "creative_id": 3,
    "name": "Special Case",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "https://affwp.dev/wp-content/images/brand-assets/affiliatewp-1v.png",
    "status": "active",
    "date": "2016-05-11 23:43:02",
    "id": 3
  },

Example creatives/{ID} response:

{
  "creative_id": 2,
  "name": "My Other Creative",
  "description": "",
  "url": "http://affiliate.dev",
  "text": "AffiliateWP Plugin Testing",
  "image": "",
  "status": "inactive",
  "date": "2016-05-11 23:35:58",
  "id": 2
}

.

3. Payouts Endpoints

AffiliateWP core 1.9+ offers two, read-only REST endpoints for payouts:

  1. payouts – Retrieves response objects for all payouts on the current site
  2. payouts/{ID} – Retrieves a response object for an payout with the given payout ID

The payout endpoints can be accessed via GET requests at the following locations:

http://example.com/wp-json/affwp/v1/payouts
http://example.com/wp-json/affwp/v1/payouts/ID

All payout endpoints and their various options are also discoverable by visiting the AffiliateWP REST namespace directly:

http://example.com/wp-json/affwp/v1/
Endpoints

The payouts endpoint accepts any valid get_payouts() arguments:

  • number – The number of results to retrieve (if available)
  • offset – The number of results to offset in the query. Default is 0 (no offset)
  • payout_id – The payout ID or array of IDs to query for.
  • affiliate_id – The affiliate ID or array of IDs to query payouts for.
  • referrals – Referral ID or array of referral IDs to retrieve payouts for.
  • amount – Payout amount (float) or min/max range (array) to retrieve payouts for.
  • amount_compare – Comparison operator used with amount. Accepts ‘>’, ‘<‘, ‘>=’, ‘<=’, ‘=’, or ‘!=’.
  • status – The payout status. Accepts ‘paid’ or ‘failed’
  • date – The date array or string to query payouts within.
  • order – How to order results. Accepts ‘ASC’ (ascending) or ‘DESC’ (descending).
  • orderby – Which field to order the response results by. Default is ‘date’
  • fields – Specific fields to return for each payout in the response. Default ‘*’ (all). Accepts ‘ids’ or any valid column

All valid arguments can also be derived by sending an OPTIONS request to the either endpoint.

The payouts/{ID} endpoint accepts any valid payout ID.

Visibility

All endpoints require the API key and token except for the main affwp/v1 endpoint.

Response

Responses are returned in JSON form.

Example payouts response:

[
  {
    "payout_id": 1,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:21",
    "owner": 0,
    "id": 1
  },
  {
    "payout_id": 2,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:24",
    "owner": 0,
    "id": 2
  },

Example payouts/{ID} response:

{
  "payout_id": 2,
  "affiliate_id": 22,
  "referrals": "2,3",
  "amount": 1,
  "payout_method": "manual",
  "status": "paid",
  "date": "2016-08-04 16:54:24",
  "owner": 0,
  "id": 2
}<br>

.

4. Referrals Endpoints

AffiliateWP core 1.9+ offers two, read-only REST endpoints for referrals:

  1. referrals – Retrieves response objects for all referrals on the current site
  2. referrals/{ID} – Retrieves a response object for an referral with the given referral ID

The referral endpoints can be accessed via GET requests at the following locations:

http://example.com/wp-json/affwp/v1/referrals
http://example.com/wp-json/affwp/v1/referrals/ID

All referral endpoints and their various options are also discoverable by visiting the AffiliateWP REST namespace directly:

http://example.com/wp-json/affwp/v1/
Endpoints

The referrals endpoint accepts any valid get_referrals() arguments:

  • number – The number of results to retrieve (if available)
  • offset – The number of results to offset in the query. Default is 0 (no offset)
  • referral_id – The referral ID or array of IDs to query for.
  • affiliate_id – The affiliate ID or array of IDs to query for.
  • reference – Reference information (product ID) for the referral.
  • ref_context – The context under which the referral was created (integration).
  • campaign – The associated campaign.
  • status – The referral status or array of statuses. Accepts ‘paid’, ‘unpaid’, ‘pending’, or ‘rejected’.
  • order – How to order results. Accepts ‘ASC’ (ascending) or ‘DESC’ (descending).
  • orderby – Which field to order the response results by. Default is ‘date’
  • search – A referral ID or the search string to query for referrals with.
  • date – The date array or string to query referrals within.
  • fields – Specific fields to return for each referral in the response. Default ‘*’ (all). Accepts ‘ids’ or any valid column

All valid arguments can also be derived by sending an OPTIONS request to the either endpoint.

The referrals/{ID} endpoint accepts any valid referral ID.

Visibility

All endpoints require the API key and token except for the main affwp/v1 endpoint.

Response

Responses are returned in JSON form.

Example referrals response:

  {
    "referral_id": 21,
    "affiliate_id": 0,
    "visit_id": 0,
    "description": "",
    "status": "",
    "amount": "",
    "currency": "",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:30",
    "payout_id": "102",
    "id": 21
  },
  {
    "referral_id": 22,
    "affiliate_id": 2736,
    "visit_id": 0,
    "description": "",
    "status": "paid",
    "amount": "1.00",
    "currency": "USD",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:43",
    "payout_id": "81",
    "id": 22
  },

Example referrals/{ID} response:

{
  "referral_id": 21,
  "affiliate_id": 0,
  "visit_id": 0,
  "description": "",
  "status": "",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2016-08-17 19:57:30",
  "payout_id": "102",
  "id": 21
}

.

5. Visits Endpoints

AffiliateWP core 1.9+ offers two, read-only REST endpoints for visits:

  1. visits – Retrieves response objects for all visits on the current site
  2. visits/{ID} – Retrieves a response object for an visit with the given visit ID

The visit endpoints can be accessed via GET requests at the following locations:

http://example.com/wp-json/affwp/v1/visits
http://example.com/wp-json/affwp/v1/visits/ID

All visit endpoints and their various options are also discoverable by visiting the AffiliateWP REST namespace directly:

http://example.com/wp-json/affwp/v1/
Endpoints

The visits endpoint accepts any valid get_visits() arguments:

  • number – The number of results to retrieve (if available)
  • offset – The number of results to offset in the query. Default is 0 (no offset)
  • visit_id – The visit ID or array of IDs to query visits for.
  • affiliate_id – The affiliate ID or array of IDs to query visits for.
  • referral_id – The referral ID or array of IDs to query visits for.
  • referral_status – The referral status or array of statuses to retrieve visits for.
  • campaign – The associated campaign.
  • order – How to order the visit in the response. Default is ‘ASC’ (ascending)
  • orderby – Which field to order the response results by. Default is ‘date’
  • fields – Specific fields to return for each visit in the response. Default ‘*’ (all). Accepts ‘ids’ or any valid column

All valid arguments can also be derived by sending an OPTIONS request to the either endpoint.

The visits/{ID} endpoint accepts any valid visit ID.

Visibility

All endpoints require the API key and token except for the main affwp/v1 endpoint.

Response

Responses are returned in JSON form.

Example visits response:

  {
    "visit_id": 1,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-20 21:58:09",
    "id": 1
  },
  {
    "visit_id": 2,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-18 21:58:11",
    "id": 2
  },

Example visits/{ID} response:

{
  "visit_id": 2,
  "affiliate_id": 5464,
  "referral_id": 0,
  "url": "http://google.com",
  "referrer": "https://affiliatewp.com",
  "campaign": "test",
  "ip": "",
  "date": "2016-09-18 21:58:11",
  "id": 2
}

.