1. Base URL and Versioning
The base URL of the Klar API is https://open-api.getklar.com/ followed by a version stringe.g. 12.2022.
Good to know: You can find a full definition of the API endpoints and the available versions in our automatically generated API specification.
2. Headers
Name | Value |
Content-Type |
|
Authorization |
|
3. Endpoint Overview and General Info
The Order API provides the following endpoints:
POST /<VERSION>/orders/validate
POST /<VERSION>/orders/json
GET /orders/status
Good to know: If a field is marked as required in the API specification it has to be present in the submission. If it's not required and present it has to have a valid value, e.g. cancelledAt can't be submitted with a 0 value and has to be set to undefined.
POST /<VERSION>/orders/validate
This endpoint allows you to check your order payload for validity. We're currently checking for violations of the specification such as required fields and attribute types, such as number, string, etc. In the future we'll also return logic violation errors as a result for an erroneous payload. The request body should contain an array of up to 1000 JSON objects of type Order.
Returns a HTTP Code 201 and the following response body:
{
"status": "VALID"
}
Returns a HTTP Code 400 and a validator message if there was an error:
[{
// ...
"children": [
{
"target": {
"descriptor": "",
"taxAmount": 0.98,
"taxRate": "17%",
"title": "string"
},
"value": "17%",
"property": "taxRate",
"children": [],
"constraints": {
"isNumber": "taxRate must be a number conforming to the specified constraints"
}
}
]
// ...
}]
Good to know: When submitting large batches of orders it might be helpful to easily identify, which order triggered a validation error. You can achieve that by adding the request parameter failedOrderIds=true to your request. The URL will then look as follows: https://open-api.getklar.com/12.2022/orders/validate?failedOrderIds=true
The returned payload will look similar to this:
"status": "INVALID",
"orderIds": [
"16933333360",
"16933333361",
"18933333360"
],
"errors": [
"orders.0.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)",
"orders.0.shipping.taxes.0.taxRate: (-24) has to be 0 or positive! (isPositive)",
"orders.1.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)",
"orders.2.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)"
]
}
POST /<VERSION>/orders/json
This endpoint allows you to upload your order data to Klar.
The request body should contain an array of up to 1000 JSON objects of type Order.
The response for a successful submission is the following JSON object with a 201 HTTP code.
{ "status": "VALID" }
The response for a invalid submission is the following JSON object with a 400 HTTP code.
{
"status": "INVALID",
"errors": [
{
"id": 1111,
"key": "0.orderId",
"message": "orderId must be a string",
"value": 1111
}
]
}
With this endpoint you can both create and update an order. As the id has to be unique, simply submit the same order again with corrected or updated fields, e.g. if the order status changes from pending to paid.
If you want to delete an order as in you don't wan't it to be processed by Klar, you can simply set the field financialStatus to 'cancelled'.
We currently don't offer an endpoint for completely deleting uploaded data. If you want to delete a submission, please write our customer support team via our in-app Chat or via [email protected].
You can also add the request parameter failedOrderIds=true to your request in order to receive the orderIds of orders we failed to validate in the return object. The URL will then look as follows: https://open-api.getklar.com/12.2022/orders/json?failedOrderIds=true The returned payload looks exactly like the one returned for validation.
GET /orders/status
This endpoint allows to query a few metrics, like the total amount of orders submitted total (only counting orders submitted on or after the 14.03.2023), the amount of orders submitted in the last submission lastBatchCount and the time of the last successful / failed submission lastSuccess / lastFailure.
Returns a HTTP 200 status code and a response body:
{
"total": "2",
"lastBatchCount": "1",
"lastSuccess": "2023-03-14T09:06:42.281Z",
"lastFailure": "2023-03-14T09:06:50.981Z"
}