Sir Filiate API

Using the API provided by Sir Filiate gives you the greatest flexibility into integration affiliate tracking into your workflow. The API allows a developer to connect the two systems in a custom way so you get the most out of both platforms.


Overview

The API is accessible via https://api.sirfiliate.com/api/{version}. (See versions).

The API reference is accessible via https://api.sirfiliate.com/api/docs. Documentation for older versions will be documented under versions.


Versions

The latest version of the API is v202107. This version will change when there are backward incompatible changes between 2 versions. The existing versions will keep working unless a written notice is given to all API users.


Authentication

The API uses API keys to authenticate. These can be created by a merchant in the merchant dashboard under Integrations > API keys.

This key is then placed into the Authorization header of the HTTP request with a perceding string "Bearer", e.g. Authorization: Beaerer MPD2I087WfWAtEuOv45M8k1jsi0Lr5EYEDeL8A7uMWomYM15y7UMVy8NW8oVpJD.


Basic transaction tracking flow

Every affiliate has a unique reference, this is either the affiliate UUID or the alias that has been given by the merchant. Sir Filiate supports tracking with both methods.

When a customer enters the website via an affiliate it's usually indicated by a GET parameter e.g. ?ref=01FNC4X70BASGXRFM7JHZREPZJ or ref=abby-medhurst.

Recording a transaction

Save this reference in a cookie or a session so you can use it later. The amount of time (usually 14 or 31 days) is up to you.

Whenever a successful transaction has been made, you can track this as a transaction in the Sir Filiate dashboard. This is done by POSTing the transaction details to the /api/{version}/transactions endpoint.

Example:

POST https://api.sirfiliate.com/api/v202107/transactions HTTP/1.1
Content-Type: application/json
Authorization: Bearer MPD2I087WfWAtEuOv45M8k1jsi0Lr5EYEDeL8A7uMWomYM15y7UMVy8NW8oVpJD
{
  "affiliate": "01FNC4X70BASGXRFM7JHZREPZJ",
  "value": 2899,
  "description": "Arbitrary description"
}

When this happens, the transaction is saved in the merchant dashboard and the commission that the affiliate will receive is recorded and returned in the response.

Cancelling a transaction

Every transaction gets a UUID that can be used to cancel the transaction if needed. Cancelling a transaction is usually done when an order is cancelled or a refund is issued.

Example:

DELETE https://api.sirfiliate.com/api/v202107/transactions/01FH089WQYW600HZCVJY31GED2 HTTP/1.1
Content-Type: application/json
Authorization: Bearer MPD2I087WfWAtEuOv45M8k1jsi0Lr5EYEDeL8A7uMWomYM15y7UMVy8NW8oVpJD

Managing affiliates

The API supports listing and creating affiliates so you can synchronize them with your own system. Information on how to create and list affiliates can be found in the API reference.