Embedding options

Tracking pages can be embedded in your shop website with our JavaScript SDK.

See Browser SDK for technical information about our JavaScript bundle.

Shopify users

If you're using Shopify, follow the Shopify tracking page setup guide instead: we strongly recommend to use the theme extension. Never add the tracking widget to your default page template — it will override all pages using that template.

Recommended approach

The simplest way to embed Karla is to add a container div and let the SDK handle all iframe configuration:

<div id="karla-container"></div>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
></script>

Why use karla-container?

Simpler integration - Just one div, no iframe attributes to remember
Automatic configuration - SDK handles security, permissions, and sizing
Future-proof - SDK updates won't require changes to your code
Dynamic height - Works seamlessly with automatic height adjustment

Alternative approach

Deprecated

While supported for backwards compatibility, we recommend using the karla-container approach above for new integrations.

If you prefer to define the iframe directly, place it before the script with the karla-frame id:

<iframe
  id="karla-frame"
  style="width: 100%;"
  frameborder="0"
  allow="clipboard-read clipboard-write fullscreen"
  sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox"
></iframe>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
></script>

By default, the tracking page url will be generated from the query parameters defined in the parent page.

orderNumber: The order number as it is defined in your shop. Can be overridden by script parameters.
zipCode: The zip code to serve as validation to show the tracking details. Can be overridden by script parameters.
token (optional): A secure, order-specific token that grants direct access to tracking details without requiring a ZIP code. Tokens can be enforced per-shop in the portal. See Order lookup methods for details.
orderName (optional): An alternative order identifier (e.g. the display name used in your shop frontend).
externalId (optional): An external order ID from a third-party system.
orderId (optional): The internal GoKarla order ID.
lang (optional): An ISO 639-1 language code. If the language code is supported, the page will be forced to that language even if the user browser has a different locale configured. If not defined, the page will be shown based on user preferences (fallback is en).

Script parameters

The bundle.min.js script accepts the following attributes:

Required attributes

data-shop-slug: Your unique shop slug (can be browsed in your shop profile in portal).
- Legacy format shop-slug is still supported for backwards compatibility

Optional attributes

data-order-number: The order number as it is defined in your shop. If not provided, the parent page URL must include an orderNumber query parameter.
data-zip-code: The zip code to serve as validation to show the tracking details. If not provided, the parent page URL must include a zipCode query parameter.
data-token: A secure, order-specific token for direct access without ZIP code validation. If not provided, falls back to the token URL query parameter. See Order lookup methods.
data-order-name: An alternative order identifier. Falls back to the orderName URL query parameter.
data-external-id: An external order ID from a third-party system. Falls back to the externalId URL query parameter.
data-order-id: The internal GoKarla order ID. Falls back to the orderId URL query parameter.
data-lang: An ISO 639-1 language code. Forces the page language. Falls back to the lang URL query parameter.
data-starter-page: The initial page to display (finder, tracking-updates, resolve, order-tracking). If not provided, defaults to order-tracking.
data-debug: Enable debug logging.

W3C Compliance

All attributes use the W3C-compliant data- prefix. While shop-slug, starter-page, and debug still support legacy formats for backwards compatibility, we strongly recommend using the W3C-compliant format for better HTML validation.

Container placement

important

The karla-container div must be placed before the script tag in your HTML. The script runs immediately and looks for the container when it executes.

Why W3C compliance matters

Using non-standard attributes can cause:

Failed HTML validation - Many enterprises require valid HTML for compliance
SEO penalties - Search engines may rank invalid HTML lower
Build failures - Some build tools and CI/CD pipelines enforce HTML validation
Accessibility issues - Screen readers and assistive technologies expect valid HTML
Future compatibility - Non-standard attributes may conflict with future HTML specifications

Order lookup methods

The SDK supports multiple ways to identify an order. The tracking page will use whichever identifiers are provided:

Method	Parameters	Use case
Order number + ZIP code	`orderNumber` + `zipCode`	Standard lookup, customer provides both values
Token-based access	`token` (+ `orderNumber`)	Secure direct access via a pre-generated link (recommended for emails and notifications)
Alternative identifiers	`orderName`, `externalId`, or `orderId`	Lookup by alternative order references from your shop or third-party systems

Recommended: token-based access

Token-based lookup is the most secure option for pre-built tracking links (e.g. in shipping confirmation emails). Each token is unique to an order and can be enforced as the only allowed lookup method per-shop in the portal. This eliminates the need for customers to enter a ZIP code.

All lookup methods are protected against enumeration attacks. Invalid or mismatched parameters result in a generic response that does not reveal whether an order exists.

Testing the iFrame

Now that we've created a new page (e.g. https://your-shop-domain/tracking), we can add our URL parameters to the URL so that the iframe is loading the given order details in the background.

Examples:

ZIP code lookup: https://your-shop-domain/tracking?orderNumber=00001&zipCode=10119
Token-based lookup: https://your-shop-domain/tracking?orderNumber=00001&token=abc123

Order finder

You can add the order finder iframe with the following snippet:

<iframe
  id="karla-frame"
  style="width: 100%;"
  frameborder="0"
  allow="clipboard-read clipboard-write fullscreen"
  sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox"
></iframe>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
  data-starter-page="order-finder"
></script>

note

Make sure that data-starter-page="order-finder" is defined in the script.

Using our API

See our API Docs to create your own tracking page.

Recommended approach​

Alternative approach​

Script parameters​

Required attributes​

Optional attributes​

Container placement​

Order lookup methods​

Testing the iFrame​

Order finder​

Using our API​