Getting Started

Generating API Keys

Calling API Functions

JSON or XML

API Call Rate Limits

Affiliate Accounts

Functions

Types

Merchant Accounts

Functions

Types

JSON or XML

By default, the Commission Factory API works with data formatted in JSON (JavaScript Object Notation), but you can easily override this.


Content Type Negotiation

The Commission Factory API supports data formatted in JSON or XML. If you call a function without specifying otherwise, the default response type will be JSON:

Request

GET /V1/Affiliate/Invoices/1?apiKey=ABC123 HTTP/1.1
Host: api.commissionfactory.com

Response

HTTP/1.1 200 OK
Content-Length: 198
Content-Type: application/json; charset=utf-8

{"Id":1,"DateCreated":"2000-01-01T00:00:00.000","DatePaid":"2000-01-01T00:00:00.000","Number":"CF-1-0001","Description":"Commissions up to 1/01/2000","SubTotal":100.0000,"GST":null,"Total":100.0000}

Function calls also support automatic content type negotation by looking for the presence of an "Accept" or "Content-Type" header, and will respond with the requested data type:

Request

GET /V1/Affiliate/Invoices/1?apiKey=ABC123 HTTP/1.1
Accept: application/xml
Host: api.commissionfactory.com

Response

HTTP/1.1 200 OK
Content-Length: 379
Content-Type: application/xml; charset=utf-8

<Invoice xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://api.commissionfactory.com/V1_1/Affiliate"><Id>1</Id><DateCreated>2000-01-01T00:00:00.000</DateCreated><DatePaid>2000-01-01T00:00:00.000</DatePaid><Number>CF-1-0001</Number><Description>Commissions up to 1/01/2000</Description><SubTotal>100.0000</SubTotal><GST>null</GST><Total>100.0000</Total></Invoice>

You can also override the automatic content type negotiation by adding a "contentType" parameter to the request. Regardless of the "Accept" or "Content-Type" headers, the "contentType" parameter will always override the response type:

Request

GET /V1/Affiliate/Invoices/1?apiKey=ABC123&contentType=application/xml HTTP/1.1
Host: api.commissionfactory.com

Response

HTTP/1.1 200 OK
Content-Length: 379
Content-Type: application/xml; charset=utf-8

<Invoice xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://api.commissionfactory.com/V1_1/Affiliate"><Id>1</Id><DateCreated>2000-01-01T00:00:00.000</DateCreated><DatePaid>2000-01-01T00:00:00.000</DatePaid><Number>CF-1-0001</Number><Description>Commissions up to 1/01/2000</Description><SubTotal>100.0000</SubTotal><GST>null</GST><Total>100.0000</Total></Invoice>

The following MIME types are supported for requests and responses:

  • application/json
  • application/xml
  • text/javascript
  • text/xml

JSONP

If you need to work with JSON data in a web browser, then you can take advantage of JSONP (JSON with Padding).

To use JSONP, you must add a "callback" parameter to the request that specifies the name of your JavaScript callback function:

Request

GET /V1/Affiliate/Invoices/1?apiKey=ABC123&callback=invoiceLoaded HTTP/1.1
Accept: text/javascript
Host: api.commissionfactory.com

Response

HTTP/1.1 200 OK
Content-Length: 214
Content-Type: text/javascript; charset=utf-8

invoiceLoaded({"Id":1,"DateCreated":"2000-01-01T00:00:00.000","DatePaid":"2000-01-01T00:00:00.000","Number":"CF-1-0001","Description":"Commissions up to 1/01/2000","SubTotal":100.0000,"GST":null,"Total":100.0000});

With JSONP, you can call an API function using a standard "script" tag, and have the response execute a callback function of your choosing. Then, when the script has finished loading, it will execute your callback function with the JSON data as a parameter.

<script type="text/javascript">
    function invoiceFailed()
    {
        alert("Invoice failed to load");
    }

    function invoiceLoaded(invoice)
    {
        alert("Invoice " + invoice.Id + " loaded successfully");
    }
</script>

<script src="https://api.commissionfactory.com/V1/Affiliate/Invoices/1?apiKey=ABC123&callback=invoiceLoaded" type="text/javascript" onerror="invoiceFailed();"></script>

Important Security Consideration

When using JSONP in a web browser, the users's API key is exposed as part of the script. To help keep API keys secure, you should take the following measures:

  • Only use JSONP on HTTPS protected web pages
  • Associate a user's API key with their account on your website
  • Require users to be logged in to your website to use JSONP
  • Never let one user have access to another user's API key