Integrate your product with Kounta by Lightspeed

API URLs

Kounta by Lightspeed’s REST API is based at https://api.kounta.com/v1/. There is no unencrypted (non-SSL) version available.

Creating a Kounta by Lightspeed Add-on

Add-ons are created and managed from within Kounta by Lightspeed. There you will find your Client ID and Client Secret for authenticating with the API.

To find out more information about creating your Kounta by Lightspeed add-on, see this knowledge base article.

Authentication

Two types of authentication are available:

• For development, you can use Basic Access Authorization.
• For production, you’ll need to use OAuth 2.0.

For more details, see the section on Authentication.

Content Type

Requests and responses will use JSON.

When sending data via POST or PUT, specify application/json as the format of the data you’re sending in the Content-Type header of your request. Any other value will result in a 400 Bad Request response status.

The format of the response body is determined by the file extension of the requested endpoint, which is .json. Alternatively, you can omit the file extension if you include the aforementioned format in your Accept header. If you omit the Accept header and the file extension, you’ll get a 406 Not Acceptable response status.

Data Types

Data in Kounta by Lightspeed is represented in these formats:

• Strings, encoded as UTF-8.
• Numbers
• Booleans, with a value of true or false.
• Dates, represented as an ISO 8601 string.
• Nulls

Understanding data types isn’t critical, but it can help you avoid problems like inadvertently trimming leading zeroes off phone numbers and rendering null as a string.

In some cases an id field with a number type may represent a 64-bit integer, in which case we will also provide an id_str string representation of that number, as some programming languages may have difficulty interpreting 64-bit integers.

Response Patterns

CRUD operations follow a few standard patterns. Deviations from these patterns are noted in the documents for individual actions.

• Successful GET requests result in 200 OK response statuses.
• Successful POST requests result in 201 Created response statuses, and Location headers containing the GET URIs of the newly created resources.
• Successful PUT requests result in 200 OK response statuses, and include the updated record in the form of the corresponding GET action.
• Successful DELETE requests result in 204 No Content response statuses.

Additionally:

• Lists of records (e.g. GET /v1/customers ) often include abridged versions of records, containing only descriptive information (e.g. name, email) and an id. In these cases, you can GET the individual records by id for more detailed records.

Pagination

When you request a list of records (e.g. GET /v1/companies/5678/customers to list all customers), you’ll receive a maximum of 25 results. To retrieve the entire result set, you’ll need to request additional pages.

Each page will include the X-Next-Page header that will contain the full URL to request the next set of 25 results. This process can be repeated until all the records have been returned.

Regarding the cursor provided by X-Next-Page:

• Cursors are complete and stateful URLs; they are used as-is without modification to fetch the next page.
• The cursor never expires. However, the data returned from a cursor in the future is not guaranteed to be the same data that was returned before.
• The format of the cursor is not guaranteed. The URL format and the state that it encapsulates may change in the future. You should not store cursor URLs for long periods of time.
• Cursors are reusable and do not have to be used in sequential order. You can iterate bidirectionally by storing previous cursor URLs and requesting them in reverse.
• Iterate until there are no more records returned, or if the X-Next-Page header is not present to retrieve all resources from a paginated API.

Caching

Responses to GET requests will include Etag headers. Subsequent requests to the same endpoints should include this header’s value in an If-None-Match header. If we send you a 304 Not Modified response, you can save bandwidth and lighten our server load by using your cached copy.

Read more about Etag headers and HTTP caching here.

Errors

Kounta by Lightspeed will use standard HTTP status codes when your requests cannot be satisfied.

Additional error information will be sent in the response body as key-value pairs, including an error code error, an error description error_description, and other diagnostically useful information.

Error responses are OAuth 2.0 compliant.

PUT vs PATCH

For simplicity, PATCH and PUT requests are identically treated as partial updates, i.e. only fields included in the request are altered. This documentation will always specify PUT, but you can use PATCH and PUT interchangeably if you like.

Testing

There are plenty of good plugins for both Firefox and Chrome for testing REST APIs.

If you prefer to use cURL or something a little less sophisticated, try sending an X-Pretty-Print: 1 header with your requests. We'll format the output with nice indentation to make it easier to read.