Overview
The Klar API allows you to push order data from any source (e.g., custom e-commerce engines, ERPs, or legacy systems) into the Klar ecosystem. Unlike synchronous APIs, Klar uses a "Landing Zone" architecture where data is ingested in raw format and processed periodically into your dashboards.
Important: This API is for SENDING data TO Klar, not for retrieving data FROM Klar.
1. Getting Started: The 3-Step Setup
To begin sending data, follow these steps:
Account Access: Ensure you have an active Klar account.
Generate Credentials: Create a Klar API Data Source within the app. This will generate a JWT (JSON Web Token) required for authentication.
Initial Push: Send your order data via a
POSTrequest to the API. You can send up to 1,000 orders in a single array of JSON objects per request.
Key Resources:
2. Understanding Data Processing
It is important to understand that the system you send data to is not the same system that displays the dashboards.
The Landing Zone: Your orders are stored in a raw format immediately upon receipt.
Processing Pipeline: Data becomes visible in the Klar frontend only after the processing pipeline runs. This happens automatically every hour.
Manual Triggers: You can force an update by clicking "Update Store Data" in your Store Settings. A loading indicator will show the status.
Debugging: If data looks incorrect, use the Order Debugger in the Data Source detail view to inspect the raw JSON Klar received.
3. Core API Logic & Endpoints
Primary Endpoint
The most important endpoint is POST /orders/json. This is the "master" endpoint for all order data.
Subset Endpoints
Klar provides specific endpoints for Refunds, COGS (Cost of Goods Sold), Logistic Costs, and Transaction Costs. These are used when your data is fragmented across different systems.
Example: If your orders come from Shopware but your logistics costs are managed in an ERP, you would use the standard Shopware connector for orders and the Logistics API endpoint for the shipping costs.
Idempotency (Updating Data)
The API is idempotent. To update an existing order (e.g., changing a status from "pending" to "paid"), simply send the order object again using the same ID.
Note: There are no specific
PATCH,PUT, orDELETEendpoints. Sending the same ID replaces the previous record in the landing zone.
4. Technical Guidelines & Pricing Logic
Versioning
Klar API URLs are prefixed with a version string.
12.2022: The legacy stable version.07.2025: The current version, which introduced support for bundled products.
Pricing and Tax Calculations
This is the most common area for integration errors. Please follow these rules strictly:
Unit-Based Values: Both discount and tax information for line items must be sent per single quantity.
Klar’s Internal Calculation:
Gross Revenue = Quantity * Product GMVNet Value = (Quantity * Product GMV) - (Quantity * Taxes) - (Quantity * Discounts)
Checksums: The fields
totalAmountBeforeandtotalAmountAfterTaxesare used only as internal checksums. All final metrics are calculated from the individual item-level values.
Bundled Products (v07.2025+)
When sending bundles, the parent object of the bundle line item is largely ignored for financial calculations. Values are calculated "bottom-up" from the individual bundle constituents.
5. Financial Status & Customizations
Klar maps your system’s order status to four internal statuses: paid, cancelled, refunded, and partially refunded.
Default Mapping: We automatically map common strings like open, pending, paid, cancelled, etc.
Custom Mapping: If your system uses unique status strings, you can apply a Data Source Customization in the Klar UI to map your custom values to our internal statuses.
6. Attribution & Pixel Matching
If you use the Klar Pixel for tracking, the order_id sent via the pixel events must match the ID sent via the API.
Klar attempts to match data using:
IDOrder NumberOrder Name
If these do not match, you must use the field optionalIdentifiers.googleAnalyticsTransactionID to ensure attribution data is linked correctly to the order.
7. Common Pitfalls to Avoid
Pitfall | Impact | Solution |
Total vs. Unit Pricing | Financial data will be multiplied incorrectly. | Always send taxes and discounts per unit, not the total for the line item. |
ID Mismatch | Marketing attribution will break. | Ensure the API |
Bundle Parent Data | Revenue might be double-counted or missed. | Ensure bundle constituents contain the accurate price/tax data. |
Batch Limits | Requests will be rejected. | Never exceed 1,000 objects per POST request. |
Status Mapping | Orders may appear in the wrong dashboard category. | Use Data Source Customizations to map non-standard status strings. |
Need more detail? Explore our Object Schemas for a full field-by-field breakdown.