ClickBank Knowledge Base /General Account Help/Tools & Features

ClickBank API

Melissa
posted this on December 26, 2012 13:09

Please note, the ClickBank API is for use by those with significant development experience.

The ClickBank API makes it possible for a wide range of computer programs to securely access ClickBank account information on behalf of ClickBank account owners. Some of the functions available to users of the API include the ability to:

  • Request a refund for a customer's purchase
  • Request a cancelation for a customer's subscription
  • Retrieve a list of transactions in a ClickBank account for a given timeframe

The possibilities for programs that make use of the ClickBank API are many and include: a dashboard that shows ClickBank data in addition to data from accounts with other online services, a subscription management tool, and an analytics package that shows data about trends in sales for a particular ClickBank account. All of these applications and more are possible with the ClickBank API. Plus they could be sold in the ClickBank Marketplace as well!

The ClickBank Service API is built on a REST architecture and provides a reliable and secure http based mechanism to retrieve data.

REST

REST is an architecture style pioneered by Roy Fielding, who was one of the principal authors of the HTTP protocol in his dissertation- "Architectural Styles and the Design of Network-based Software Architectures." A brief introduction to REST can be found in the Wikipedia article Representational State Transfer

Versioning

The current version of ClickBank's Service API is: 1.3.

The version information is part of the URL to access the services. This provides the following benefits:

  • Clear information about what version of the API is being used
  • An easy to understand upgrade path when new API versions are announced

Infrastructure

ClickBank's REST API is based on JSR-311 - The Java API for RESTful Web Services. This is an implementation detail for the ClickBank Service API. The services themselves are HTTP based and implementation agnostic; therefore, any web client (.NET, PHP, Java, Python, Ruby, etc) can utilize the services.

While ClickBank does not endorse any REST tools for development, we do find RestClient to be very helpful while developing and testing RESTful web services.

Request Header

ClickBank's Service API Header consists of security, output, and page parameters. The ClickBank Service API only accepts query parameters; requests built on form based (post) parameters are ignored.

The HTTP spec indicates that a URL cannot be more than 2k in length. API developers should ensure that the length of the API rest url’s are less than 2000 characters.

Certification

With some programming languages the ClickBank's Service API will require your system to possess a certificate for the following domain:

*.clickbank.com

To acquire the certificate, simply go to the following URL, double click the authentication lock in the lower right-hand corner of your browser, and save the certificate to your system

https://api.clickbank.com/rest/1.3/orders

Security

ClickBank's Service API methods are secure and will return a 403 [Forbidden] status code if accessed without the right credentials. Secure access to the API requires an Authorization header parameter containing the following keys:

  • Developer key - The Developer key grants the user the "ROLE_HAS_DEVELOPER_KEY" role.
  • Clerk user key - The Clerk key grants the user either the "ROLE_API_ORDER_READ" or "ROLE_API_ORDER_WRITE" role.

Conceptually, a developer key is a token which is generally used to allow access to the API's; while a clerk user API key is generally associated with a particular user.  When creating the header parameter with both roles, each value must be separated by a colon.

Example:

Authorization DEV-F7F8023A486E9A9602FFDA2765E1925:API-9870acb8d96f8bd18c2eb70725b01fe4b98ece58

Some of the ClickBank Service APIs (most notably the sandbox) do not require both keys. The Supported API documentation lists the required roles to access a particular service. If only the developer key is required, a colon in the header parameter is not necessary.

Example:

Authorization DEV-F7F8023A486E9A9602FFDA2765E1925

To acquire Developer and Clerk keys, see our article on using a ClickBank Master Account. Each key must be approved, present, and active for successful authentication to occur.

Output

ClickBank's Service API supports the following output formats:

  • XML
  • JSON
  • CSV (only work with the Orders API)

Request the output format by including an Accept parameter in the http header. If an unsupported format is requested the server will provide a 500 [Internal Server Error] status code.

Example:

Accept application/xml

Pagination

The API will never return more than a 100 rows for any service call. For requests that contain more than 100 rows of data, the API will return the first 100 rows with a status code of 206 [Partial Content]. To retrieve the additional pages, the developer must include a Page header parameter indicating which page of the result is desired.

Example:

Page 3

Once the last page is accessed, the service will return a 200 [OK] instead of a 206 [Partial Content].

ClickBank API Limitations

The ClickBank API handles a large number of operations. To protect the system from receiving more operations than it can handle, and to ensure an equitable distribution of system resources, it is necessary to employ a quota system. Our policies are as follows and in support of the API Terms of Service. Note: These are subject to change.

All applications under a single project share any per project limits.

General API quotas:

•        25,000 requests per account per day
•        5 queries per second (QPS) per IP

If quota is exceeded, ClickBank API returns an error for additional requests: HTTP status code 403 Forbidden and a message indicating that the specific account has insufficient quota to proceed.

If you think that your application needs additional daily quota, you can request more quota by contacting our Customer Service team. Please provide a brief explanation of why you need this additional quota.

Supported APIs

For version 1.3, the following API's will be supported:

Each ClickBank API is self-describing. For service description details, simply access the API URL.

Additional Tools

Debugging

The ClickBank API provides a debug web service [/rest/1.3/debug]. The service prints out the request context information [including the security context information], which can be very useful when correcting REST API issues.

Code Samples

The following code samples demonstrate how a developer might utilize the APIs:

A) C# - https://api.clickbank.com/api/api_13_examples/api_example.csharp

B) Java - https://api.clickbank.com/api/api_13_examples/api_example.java

C) PHP - https://api.clickbank.com/api/api_13_examples/api_example.php

D) Python - https://api.clickbank.com/api/api_13_examples/api_example.py

E) Ruby - https://api.clickbank.com/api/api_13_examples/api_example.rb

For ETL developers who wish to use the Talend Open Studio IDE, one of our developers has created tools that can assist with Java development. They can be downloaded for free here:

http://talendforge.org/exchange/tos/ (Click on link and then type in clickbank in Category Search box, then click Filter)

The following post shows how to use these tools:

http://talendforge.org/forum/viewtopic.php?id=12061

 
Topic is closed for comments