REST API Extended – Managing Visits

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

All five endpoints leverage the same two route patterns:

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

Visits can be created by sending a POST or PUT request to the visits route:

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

The create endpoint accepts any of the following arguments:

  • affiliate_id – (integer) ID of the affiliate to associate with the visit. This field is required.
  • referral_id – (integer) ID of the referral to associate with the visit.
  • url – (string) Visit URL.
  • referrer – (string) Referring URL
  • campaign – (string) Associated campaign.
  • ip – (string) IP address of the visitor.

Creating a visit:

Method: PUT/POST
Endpoint: https://example.com/wp-json/affwp/v1/visits/?affilite_id=30&url=https%3A%2F%2Faffiliatewp.com

The above would create a new visit associated with affiliate ID 30 that has a stored URL of https://affiliatewp.com.

Example response:

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "",
  "ip": "",
  "date": "2017-01-26 23:05:21",
  "id": 541
}

Editing an Existing Visit

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

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

The edit endpoint accepts any of the following arguments:

  • visit_id – (integer) ID of the visit. This field is required.
  • referral_id – (integer) ID of the referral to associate with the visit.
  • affiliate_id – (integer) ID of the affiliate to associate with the visit.
  • url – (string) Visit URL.
  • referrer – (string) Referring URL
  • campaign – (string) Associated campaign.
  • ip – (string) IP address of the visitor.

Updating a Visit

In this example, we'll update a visit's associated campaign:

Method: POST/PATCH
Endpoint: https://example.com/wp-json/affwp/v1/visits/541?campaign=spring-sale

Response:

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "spring-sale",
  "ip": "",
  "date": "2017-01-26 23:05:21",
  "id": 541
}

Deleting a Visit

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

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

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

Example request:

Method: DELETE
Endpoint: https://example.com/wp-json/affwp/v1/visits/541

Response:

{
  "deleted": true,
  "previous": {
    "visit_id": 541,
    "affiliate_id": 30,
    "referral_id": 0,
    "url": "https://affiliatewp.com",
    "referrer": "",
    "campaign": "spring-sale",
    "ip": "",
    "date": "2017-01-26 23:05:21",
    "id": 541
  }
}

.