1. Base URL and Versioning
The base URL of the Klar API is https://open-api.getklar.com/ followed by a version string, e.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. Endpoint Overview and General Info
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.
The COGS API provides the following endpoints:
POST /<VERSION>/cogs/validate
POST /<VERSION>/cogs/json
GET /cogs/status
POST /<VERSION>/logistics-costs/validate
This endpoint allows you to check your COGS 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 a JSON object with the key "items" that can contain an array of up to 1000 JSON objects of type COGS.
Returns a HTTP Code 202 and the following response body:
{
"status": "VALID"
}Returns a HTTP Code 400 and a validator message if there was an error:
[{
// ...
"children": [
{
"target": {
// ... COGS object
},
"value": null,
"property": "productCogs",
"children": [],
"constraints": {
"isNumber": "productCogs must be a number conforming to the specified constraints"
}
}
]
// ...
}]
POST /<VERSION>/cogs/json
This endpoint allows you to upload your logistics costs data to Klar.
The request body should contain an array of up to 1000 JSON objects of type COGS. The response for a successful submission is an empty response with a 201 HTTP code.
With this endpoint you can both create and update COGS. Simply submit the same COGS again with corrected or updated fields, e.g. if the amount of COGS for a line item of an order changes.
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].
GET /cogs/status
This endpoint allows to query a few metrics, like the total amount of refunds submitted total, the amount of COGS 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": "9",
"lastBatchCount": "4",
"lastSuccess": "2023-03-11T12:13:31.193Z",
"lastFailure": "2023-03-11T09:06:50.321Z"
}