Skip to main content
COGS

Use this endpoint if COGS (Costs of Goods Sold) are coming from a non-shop system source & order data doesn't contain COGS information.

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. 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"
}

Did this answer your question?