# Orders \(API Endpoint\)

## 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](https://api.getklar.com/public/docs#data-ingestion/description/introduction).

## **2. Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

## 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](https://api.getklar.com/public/docs#data-ingestion/description/introduction) 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](https://help.getklar.com/en/articles/9346875-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](https://help.getklar.com/en/articles/9346875-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 <support@getklar.com>.

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