Documentation » Billing

Documentation for the integration of the Canyan billing system with external systems.

API Documentation

The is built on GraphQL principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We recommend using SSL encryption by issuing requests through HTTPS if available, however it’s not enforced.

The API is versioned to implement changes which break backwards compatibility. Current API version is 1, and its endpoint is:


All requests to API require you to authenticate yourself to the service using JSON Web Token. In order to do this you must send a valid Authorization HTTP header with your API token. More information about JSON Web Token (RFC7519) on the official JWT website.

This is your current token:


HTTP response codes

  • 200 OK
    Everything went smooth and the request has been processed.
    NOTE: this doesn't mean the requested action has been succesfully performed, it just means the API request has been accepted and processed.
  • 400 Bad Request
    Something with the message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON {error: ...} with an API error code and message containing details on what went wrong.
  • 401 Unauthorized
    Missing or incorrect API token in header.

No XML, just JSON

We only support JSON for serialization of data. Our format is to have no root element and we use snake_case to describe attribute keys. This means that you have to send Content-Type: application/json; charset=utf-8 when you're POSTing or PUTing data. Let's stress it out: All API accept and return JSON only.

Handling errors

If we are having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It's your responsibility in all of these cases to retry your request later.

Identify your app

You must include a User-Agent header with the name of your application and a link to it or your email address so we can get in touch in case you're doing something wrong (so we may warn you before you're blacklisted) or something awesome (so we may congratulate you). Here's a couple of examples:

User-Agent: MyApp (
  User-Agent: Fabio's Ingenious Integration (

If you don't supply this header, you will get a 400 Bad Request response.

Help us make it better

Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please get in touch with us: we are more than happy to tweak our APIs to fulfill your needs.