# Komfortkasse API ## Description This is version `2.0.0` of this API documentation. Last update on May 1, 2026. ![Komfortkasse Logo](https://komfortkasse.eu/images/logo_trans.png) The Komfortkasse API allows you to send orders to Komfortkasse and get their status back (for example, whether they have been paid). This is Version 2 of the API. Version 1 (deprecated, not available to new customers) can be found at (PDF only). ## Overview ### Process flow A normal process flow without any reminders or cancellations: 1. Your customer places an order in your store using a payment method supported by Komfortkasse (prepayment, invoice, COD) 2. The order is transmitted to Komfortkasse using `POST /orders` (or `POST /order/{orderNumber}` for a single order) 3. Optional: Upload an invoice PDF for the order with `POST /order/{orderNumber}/invoice/{invoiceNumber}` 4. The customer pays the order and Komfortkasse sets `paymentStatus` to `PAID` 5. You read all orders periodically using e.g. `GET /orders?paymentStatus=PAID` and discover that the order has been paid 6. Optional manual interventions: - `POST /order/{orderNumber}/setpaid` — mark an order as paid manually - `POST /order/{orderNumber}/setunpaid` — revert a manual `setpaid` - `POST /order/{orderNumber}/cancel` — cancel an order (sets `paymentStatus` to `CANCELLED`) - `POST /order/remove/{orderNumber}` — mark an order as removed externally (sets `paymentStatus` to `DISAPPEARED`); use this when the order vanished from your shop (e.g. cancelled by the customer or deleted by an admin) and should no longer be tracked by Komfortkasse; use `cancel` instead to record an explicit cancellation ### Callback / Webhook You can register a Callback URL in Komfortkasse's API access settings (menu Settings → Shop). If enabled, Komfortkasse will send a callback in the format of [Get Order Details](#operation/getOrder) for every payment status change. Answer with HTTP 200. If the callback is not successful, Komfortkasse will retry roughly every 15 minutes for up to 7 days. Komfortkasse will send the **Callback Access Code** available in the Komfortkasse merchant area as HTTP header `X-Komfortkasse-Access-Code`. Verify this header value. For extra security, allow callbacks only from [Komfortkasse's IP addresses](https://komfortkasse.freshdesk.com/support/solutions/articles/14000152603). ### Security For security purposes, use HTTPS requests only. ## Formats - **Date:** `dd-MM-yyyy` - **Decimal numbers:** `0.00` ## Error handling Errors are signalled with standard HTTP status codes: | Status | Meaning | |--------|---------| | `200` | Success | | `400` | Error | | `401` | Authorization problem | | `404` | Not found | | `500` | Internal server error (unexpected; please retry or contact support if it persists) | In case of an error, the response body contains an `Error` object as defined in the [Error schema](#components/schemas/Error). Example: ```json { "error": "API Key missing" } ``` ### Common error messages | Status | `error` message | Meaning | |--------|-----------------|---------| | `401` | `Authentication header not present` | The `X-Komfortkasse-API-Key` header is missing. | | `401` | `Invalid authentication header` | The API key is unknown or no longer valid. | | `401` | `Replace '[your API key]' with the API key from the merchant area` | The literal placeholder string was sent instead of a real key. | | `400` | `API not active, contact support` | API access is disabled for this shop. | | `400` | `Update not allowed for non-API Shop` | Write operation attempted on a shop that only allows reads via the API. | | `400` | `Shop not active` | The shop is not in an active status (e.g. paused, deleted). | | `400` | `Missing body` | Request body is empty or could not be parsed. | | `400` | `Missing parameter ` | A required field on the request body is missing or empty. | | `400` | `Invalid date: , format should be dd-MM-yyyy` | A date query parameter does not match the required format. | | `400` | `Parameter date is not valid` / `Parameter dueDate is not valid` | The order's `date` or `dueDate` could not be parsed. | | `400` | `Parameter date must not be in the future` | `date` is set to a future timestamp on a new order. | | `400` | `Parameter dueDate must not be more than 6 months in the future` | `dueDate` is too far ahead. | | `400` | `Parameter number and number in object do not match` | Path `orderNumber` and body `number` differ. | | `400` | `Parameter initialDunningLevel can only be given when creating a new order` | `initialDunningLevel` was sent on an update. | | `400` | `Could not acquire lock` | The same order is being updated concurrently — retry. | | `400` | `Could not update order ()` | Update was rejected (e.g. status no longer allows changes). | | `400` | `Refund already exists: ` | A refund with the same `externalReference` already exists. | | `400` | `Planned date must be in the future` | `plannedDate` on a refund must be in the future. | | `400` | `Invalid JSON, comments not allowed in JSON body` | The body contains HTML comments / non-JSON content. | | `400` | `File missing` / `File size 0` | Invoice upload missing or empty. | | `400` | `Order already in paymentStatus PAID` | `setpaid` called on an already-paid order. | | `400` | `Order must have paymentStatus PAID` / `Order must have manual paymentStatus` | Preconditions for `setunpaid` not met. | | `404` | `Order '' not found` / `Order not found` | Unknown order number for the authenticated shop. | > When using a malformed URL, you might not receive an error object but a blank page. When using a completely invalid URL (e.g. without `/api`) you might also be redirected to the Komfortkasse merchant area login page. ## Rate limits There is no hard rate limit. Please throttle bulk submits and split lists larger than 100 orders into multiple `POST /orders` calls to avoid timeouts. ## Timeouts Some operations (e.g. `Sync Orders`) may take a long time. Allow a timeout of **at least 10 minutes**. ## Example Implementation A sample implementation in PHP is available at . ## Servers - Production: https://ssl.komfortkasse.eu/api/v2 (Production) ## Authentication ## Groups and operations ### [Single Order](https://apidocs.komfortkasse.eu/group/endpoint-single-order.md) - [Get Order Details](https://apidocs.komfortkasse.eu/operation/operation-getorder.md) - [Submit Order](https://apidocs.komfortkasse.eu/operation/operation-submitorder.md) - [Remove Order](https://apidocs.komfortkasse.eu/operation/operation-removeorder.md) - [Set Order paid](https://apidocs.komfortkasse.eu/operation/operation-setorderpaid.md) - [Set Order unpaid](https://apidocs.komfortkasse.eu/operation/operation-setorderunpaid.md) - [Cancel Order](https://apidocs.komfortkasse.eu/operation/operation-cancelorder.md) - [Create a refund for an order](https://apidocs.komfortkasse.eu/operation/operation-createrefund.md) - [Submit an invoice file](https://apidocs.komfortkasse.eu/operation/operation-submitinvoice.md) ### [Bulk Orders](https://apidocs.komfortkasse.eu/group/endpoint-bulk-orders.md) - [Read Orders](https://apidocs.komfortkasse.eu/operation/operation-readorders.md) - [Submit Orders](https://apidocs.komfortkasse.eu/operation/operation-submitorders.md) - [Sync Orders](https://apidocs.komfortkasse.eu/operation/operation-syncorders.md) ### [Postings](https://apidocs.komfortkasse.eu/group/endpoint-postings.md) - [Read Postings](https://apidocs.komfortkasse.eu/operation/operation-readpostings.md) ### [Image](https://apidocs.komfortkasse.eu/group/endpoint-image.md) - [Get Image](https://apidocs.komfortkasse.eu/operation/operation-getimage.md) [Powered by Bump.sh](https://bump.sh)