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 Refunds API provides the following endpoints:
POST /<VERSION>/refunds/validate
POST /<VERSION>/refunds/json
GET /refunds/status
POST /<VERSION>/refunds/validate
This endpoint allows you to check your refunds 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 Refund.
Returns a HTTP Code 200 and the following response body:
{ "status": "VALID" }
Returns a HTTP Code 400 and a validator message if there was an error:
[{
// ...
"children": [
{
"target": {
// ... refund object
},
"value": null,
"property": "refundedQuantity",
"children": [],
"constraints": {
"isNumber": "refundedQuantity must be a number conforming to the specified constraints"
}
}
]
// ...
}]
POST /<VERSION>/refunds/json
This endpoint allows you to upload your refunds data to Klar.
The request body should contain an array of up to 1000 JSON objects of type Refund. The response for a successful submission is an empty response with a 201 HTTP code.
With this endpoint you can both create and update a refund. As the id has to be unique, simply submit the same refund again with corrected or updated fields, e.g. if the amount of refunded lineItems of an order changes.
If you want to delete the refunds as in you don't wan't it to be processed by Klar, you can simply submit an empty array for field lineItems.
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 /refunds/status
This endpoint allows to query a few metrics, like the total amount of refunds submitted total, the amount of refunds 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"
}