Logistics Costs

Use this endpoint to import logistics costs missing in your shop system / are coming via another system, e.g. ERP.

Frank Birzle avatar
Written by Frank Birzle
Updated over a week ago

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. 04.2024.

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 Logistics Costs API provides the following endpoints:

  • POST /<VERSION>/logistics-costs/validate

  • POST /<VERSION>/logistics-costs/json

  • GET /logistics-costs/status

POST /<VERSION>/logistics-costs/validate

This endpoint allows you to check your logistics-costs 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 LogisticsCosts.

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": {
// ... LogisticsCosts object
},
"value": null,
"property": "logisticsCosts",
"children": [],
"constraints": {
"isNumber": "logisticsCosts must be a number conforming to the specified constraints"
}
}
]
// ...
}]

POST /<VERSION>/logistics-costs/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 LogisticsCosts. The response for a successful submission is an empty response with a 201 HTTP code.

With this endpoint you can both create and update logistics costs. Simply submit the same logistics costs again with corrected or updated fields, e.g. if the amount of logistics costs spent for 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 /logistics-costs/state

This endpoint allows to query a few metrics, like the total amount of refunds submitted total, the amount of 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"
}

Did this answer your question?