Setting up the Klar Pixel via serverside tracking

Instead of deploying a JS tracking script, you send events directly to Klar's server-side endpoint via HTTP POST requests. You still need to create a Klar Pixel datasource first to get your dataSourceId.

Step 1: Add the Klar Pixel datasource

If you have multiple domains, create a separate Pixel datasource for each store.

Go to Store Configurator → Data Sources and click Add New Data Source
Select the Datasource Klar Pixel
Enter a name — e.g. "Klar Tracking Script"
Select Basic tracking and click Configure

Why Basic? For server-side tracking, you're not deploying a JavaScript tag that runs under your own subdomain — you're sending events directly from your server. Domain Validated tracking is only relevant for client-side scripts.

Copy the datasource ID from the configuration screen — you'll need this as the dataSourceId field in every event payload

This then needs to be used as the dataSourceId in all of the events you are sending.

Step 2: Implement the klar script in the server-side events

Endpoint

All events are sent as POST requests to:

POST https://september.durchsichtig.xyz/server-side-event/{EVENT_NAME}

Where {EVENT_NAME} matches the eventName field in the payload.

Required headers

Content-Type: application/json

x-serverside-ip: <customer's IP address>

The x-serverside-ip header is required so Klar can use the IP address for session stitching and identity resolution — the same way a client-side script would capture it automatically.

Key field: `septemberId`

Every event requires a septemberId — a 16-character nanoid that identifies the user across sessions. This must be the same value for all events from the same user, so it should be generated once and persisted client-side (e.g. in a first-party cookie). You can generate one using a library like nanoid.

Error handling

When a request is malformed, the server returns 400 with an X-Klar-Failure header:

Header value	Meaning
`read-headers`	Missing or invalid headers
`get-body`	Wrong format or missing request body
`invalid-json`	Request body is not valid JSON

Base event schema

All events extend this base schema:

interface BaseEvent {
  eventName: string;           // Required — the specific event type
  createdAt: string;           // Required — ISO 8601 timestamp
  pageUrl: string;             // Required — current page URL
  septemberId: string;         // Required — 16-character nanoid (see above)
  googleAnalyticsId: string;   // Required — value of the _ga cookie
  facebookId: string;          // Required — value of the _fbp cookie
  dataSourceId: string;        // Required — datasource ID from Step 1
  referrer: string;            // Required — previous page URL
  hasGivenConsent: boolean;    // Required — user consent status
  customerId: string;          // Required — customer identifier
  screen: string;              // Required — screen resolution (e.g. "1920x1080")
  shopSystem: string;          // Required — e-commerce platform (e.g. "shopify")
}

All createdAt fields must be in ISO 8601 format. Fields marked with ? in the event schemas below are optional but recommended when available.

2.1 VisitEvent

Fire on every page visit.

interface VisitEvent extends BaseEvent {

eventName: "VisitEvent";

pageTitle: string; // Required — title of the current page

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/VisitEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "VisitEvent",
    "pageTitle": "Best Product of the World",
    "createdAt": "2024-04-11T11:11:15.783Z",
    "pageUrl": "https://getklar.com/dogs",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://google.de",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "1920x1200",
    "shopSystem": "shopify"
  }'

2.2 ProductViewedEvent

Fire when a customer views a product page.

interface ProductViewedEvent extends BaseEvent {

eventName: "ProductViewedEvent";

productId: string; // Required — either productId OR productSku must be provided

productSku: string; // Required — either productId OR productSku must be provided

productTitle?: string; // Optional — product name

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/ProductViewedEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "ProductViewedEvent",
    "productId": "46667923652922",
    "productTitle": "Best Dog TransportBOX",
    "productSku": "F0011",
    "createdAt": "2024-04-11T11:22:43.984Z",
    "pageUrl": "https://getklar.com/dogs/transport",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "1920x1200",
    "shopSystem": "shopify"
  }'

2.3 AddToCartEvent

Fire when a product is added to the cart.

interface AddToCartEvent extends BaseEvent {

eventName: "AddToCartEvent";

productId: string; // Required — either productId OR productSku must be provided

productSku: string; // Required — either productId OR productSku must be provided

productTitle?: string; // Optional — product name

productQuantity: number; // Required — quantity added

productPrice?: number; // Optional — product price

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/AddToCartEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "AddToCartEvent",
    "productId": "46667923652922",
    "productSku": "F0011",
    "productTitle": "Best Dog TransportBOX",
    "createdAt": "2024-04-11T11:27:06.262Z",
    "pageUrl": "https://getklar.com/dogs/transport",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs",
    "hasGivenConsent": true,
    "customerId": "cust_987654321",
    "screen": "3840x2160"
  }'

2.4 RemoveFromCartEvent

Fire when a product is removed from the cart.

interface RemoveFromCartEvent extends BaseEvent {

eventName: "RemoveFromCartEvent";

productId: string; // Required — either productId OR productSku must be provided

productSku: string; // Required — either productId OR productSku must be provided

productTitle?: string; // Optional — product name

productQuantity: number; // Required — quantity removed

productPrice?: number; // Optional — product price

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/RemoveFromCartEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "RemoveFromCartEvent",
    "productId": "46667923652922",
    "productSku": "F0011",
    "productTitle": "Best Dog TransportBOX",
    "productQuantity": 1,
    "productPrice": 8.5,
    "createdAt": "2024-04-11T11:35:45.000Z",
    "pageUrl": "https://getklar.com/cart",
    "septemberId": "m1n2b3v4c5x6z7l8",
    "googleAnalyticsId": "GA1.2.3456789012.3456789012",
    "facebookId": "fb.1.3456789012.3456789012",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/product/f0011",
    "hasGivenConsent": true,
    "customerId": "cust_2468101214",
    "screen": "2560x1440"
  }'

2.5 UpdateCheckoutEvent

Fire when a customer enters the checkout.

interface UpdateCheckoutEvent extends BaseEvent {

eventName: "UpdateCheckoutEvent";

checkoutId: string; // Required — checkout session identifier

cartId?: string; // Optional — shopping cart identifier

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/UpdateCheckoutEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "UpdateCheckoutEvent",
    "checkoutId": "7297e4e6e7c95f2e8c3da4c66d60f7e7",
    "createdAt": "2024-04-11T11:29:32.929Z",
    "pageUrl": "https://getklar.com/checkouts/cn/Z2NwLWV1cm9wZS13ZkVKSz",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs/transport",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "3840x2160",
    "shopSystem": "shopify"
  }'

2.6 PaymentInfoEvent

Fire when payment information is entered during checkout.

interface PaymentInfoEvent extends BaseEvent {

eventName: "PaymentInfoEvent";

checkoutId: string; // Required — checkout session identifier

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/PaymentInfoEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "PaymentInfoEvent",
    "checkoutId": "chk_def456",
    "createdAt": "2024-04-11T11:30:10.512Z",
    "pageUrl": "https://getklar.com/checkout/payment",
    "septemberId": "z9y8x7w6v5u4t3s2",
    "googleAnalyticsId": "GA1.2.2345678901.2345678901",
    "facebookId": "fb.1.2345678901.2345678901",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/shipping",
    "hasGivenConsent": true,
    "customerId": "cust_123456789",
    "screen": "1920x1080"
  }'

2.7 ShippingInfoEvent

Fire when shipping information is entered during checkout.

interface ShippingInfoEvent extends BaseEvent {

eventName: "ShippingInfoEvent";

checkoutId: string; // Required — checkout session identifier

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/ShippingInfoEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "ShippingInfoEvent",
    "checkoutId": "chk_jkl012",
    "createdAt": "2024-04-11T11:40:00.000Z",
    "pageUrl": "https://getklar.com/checkout/shipping",
    "septemberId": "o9p8q7r6s5t4u3v2",
    "googleAnalyticsId": "GA1.2.4567890123.4567890123",
    "facebookId": "fb.1.4567890123.4567890123",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/cart",
    "hasGivenConsent": true,
    "customerId": "cust_135791113",
    "screen": "1280x800"
  }'

2.8 OrderEvent

Fire on the order confirmation page after the purchase is complete.

interface CheckoutItem {

productId?: string; // Optional — either productId or productSku required if item present

productSku?: string; // Optional — either productId or productSku required if item present

productTitle?: string; // Optional — product name

productQuantity?: number; // Optional — quantity ordered

productPrice?: number; // Optional — product price

}

interface OrderEvent extends BaseEvent {

eventName: "OrderEvent";

orderId: string; // Required — unique order identifier

checkoutId: string; // Required — checkout session identifier

customerId?: string; // Optional — customer identifier

cartId?: string; // Optional — shopping cart identifier

checkoutItems?: CheckoutItem[]; // Optional — array of purchased items

shippingTotal?: number; // Optional — shipping cost

checkoutTax?: number; // Optional — tax amount

checkoutTotal?: number; // Optional — total order amount

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/OrderEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "OrderEvent",
    "orderId": "5916248703148",
    "checkoutId": "7282c2584c907ddcd9f17dd01f374137",
    "customerId": "cust_123456",
    "checkoutItems": [{
      "productId": "42897447452844",
      "productSku": "12345",
      "productTitle": "Dog BOX",
      "productQuantity": 1,
      "productPrice": 0
    }],
    "shippingTotal": 0,
    "checkoutTax": 0,
    "checkoutTotal": 629.95,
    "createdAt": "2024-04-11T11:35:18.474Z",
    "pageUrl": "https://getklar.com/checkouts/cn/Z2NwLWV1cm9wZS13ZkVKSz",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs/transport",
    "hasGivenConsent": true,
    "screen": "3840x2160"
  }'

2.9 UpdateABGroupEvent

Fire when a user is assigned to an A/B testing group.

interface UpdateABGroupEvent extends BaseEvent {

eventName: "UpdateABGroupEvent";

projectName?: string; // Optional — A/B test project name

variantName: string; // Required — assigned variant (e.g. "VariantA", "VariantB")

experimentName: string; // Required — experiment identifier

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/UpdateABGroupEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "UpdateABGroupEvent",
    "projectName": "HomepageRedesign",
    "variantName": "VariantB",
    "experimentName": "Spring2024Experiment",
    "createdAt": "2024-04-11T11:50:00.000Z",
    "pageUrl": "https://getklar.com/landing/ab-test",
    "septemberId": "r5t6y7u8i9o0p1q2",
    "googleAnalyticsId": "GA1.2.5678901234.5678901234",
    "facebookId": "fb.1.5678901234.5678901234",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/home",
    "hasGivenConsent": true,
    "customerId": "cust_1112131415",
    "screen": "1920x1080"
  }'

2.10 CustomConversionEvent

Before firing this event, set up your custom conversions in Klar:

Go to Store Configurator → Store Settings
Define your custom conversions — assign an ID to a descriptive name (e.g. 1 = Add to Cart). This ID is the customConversionId you'll pass in the event payload.

interface CustomConversionEvent extends BaseEvent {

eventName: "CustomConversionEvent";

customConversionId: number; // Required — ID defined in Store Settings

customConversionValue?: number; // Optional — conversion value

}

Example:

curl -X POST https://september.durchsichtig.xyz/server-side-event/CustomConversionEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "CustomConversionEvent",
    "customConversionId": 101,
    "customConversionValue": 49.99,
    "createdAt": "2024-04-11T12:00:00.000Z",
    "pageUrl": "https://getklar.com/thank-you",
    "septemberId": "g7h8j9k0l1m2n3b4",
    "googleAnalyticsId": "GA1.2.6789012345.6789012345",
    "facebookId": "fb.1.6789012345.6789012345",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/complete",
    "hasGivenConsent": true,
    "customerId": "cust_1617181920",
    "screen": "1440x900"
  }'

Step 3: Add the data privacy snippet

Add Klar's data privacy snippet to your shop's privacy policy. You'll find it inside the Klar Pixel datasource settings, below the tracking script, in the collapsed "Data Protection Snippet" section — available in both German and English.

Step 4: Set up the Klar URL parameters in your ad accounts

To match conversions and costs accurately across channels, add Klar's tracking parameters to your ad account URLs:

Here are guides on how to do that for each marketing channel:

🔵 URL Parameters for Meta Ads

🟢 URL Parameters for Google Ads

URL Parameters for TikTok Ads

🔴 URL Parameters for Pinterest Ads

✉️ URL Parameters for Klaviyo

😍 URL Parameters for Influencers/Affiliates

🟣 URL Parameters for Taboola

🟠 URL Parameters for Outbrain

URL Parameters for Bing

🎨 URL Parameters for All Other Channels

What happens next?

Klar will start tracking visitors and purchase activity immediately. Attribution data appears in your reports from the next day onwards — note that it's only available from the point in time the events started firing, not retroactively.

If you run into any issues, reach out via the in-app chat.

Setting up the Klar Pixel via serverside tracking

Step 1: Add the Klar Pixel datasource

Step 2: Implement the klar script in the server-side events

Endpoint

Required headers

Key field: septemberId

Error handling

Base event schema

2.1 VisitEvent

2.2 ProductViewedEvent

2.3 AddToCartEvent

2.4 RemoveFromCartEvent

2.5 UpdateCheckoutEvent

2.6 PaymentInfoEvent

2.7 ShippingInfoEvent

2.8 OrderEvent

2.9 UpdateABGroupEvent

2.10 CustomConversionEvent

Step 3: Add the data privacy snippet

Step 4: Set up the Klar URL parameters in your ad accounts

What happens next?

Key field: `septemberId`