API documentation

# Tracking orders and conversions

The ordering flow runs on the Iteras server, usually inside an iframe on your site, so your analytics cannot see it directly. This guide describes mechanisms for tracking what happens, both client-side and server-side. Combine them as needed.

Iteras does not track visitors or load any analytics on its own, since that usually requires consent that only you can collect. Each mechanism here is something you set up, and handling consent around it is your responsibility.

# Tracking what happens in the iframes

Iteras has a little API for sending client-side tracking events to your pages from inside the iframes that you can then listen to. The listener runs on your page, where your consent management and analytics are already set up, and nothing loads inside the iframe. So this is the mechanism we recommend for an ordering form embedded on your page.

The way it works is that code added through the code customization fields in the customer service settings runs inside the self-service and ordering pages. From there, Iteras.track(jsonData) sends the given JSON data out of the iframe. Simple page load tracking of the ordering pages could look like this:

<script>
 document.addEventListener('DOMContentLoaded', function() {
   if (document.body.classList.contains("ordering-base"))
     Iteras.track({ "type": "page-load", "page": document.body.dataset.page });
 });
</script>

The body element carries a class for the section and a data-page attribute naming the specific page, so you can scope what you send and tell the pages apart. If you want to track the self-service pages as well, simply drop the class list check.

On your page, an iteras-track DOM event bubbles up carrying the sent data in event.detail.data. The event bubbles from the iframe element, so a listener on document catches events from all Iteras iframes on the page:

document.addEventListener("iteras-track", function (e) {
  console.log("Got tracking event:", e.detail.data);
});

The listener requires iteras.js on the embedding page (see the Javascript API) - it is what converts the message from the iframe into the DOM event.

# Carrying tracking parameters to the finished page

After the last step of the flow, Iteras redirects out of the iframe and loads a page as the top-level page. If it's part of a paywall offering, this would usually be the page the visitor came from. Otherwise the given next parameter on the ordering iframe, the return_url of the place order API, or the redirect URL configured on the ordering form. That page is an ordinary page view on your site, where your analytics runs as usual, so you can fire a conversion event there.

Attribution or marketing campaign GET parameters on the page embedding the iframe do not travel through the flow by themselves. If these parameters should be visible on the finished page, copy them onto the next URL when generating the iframe:

var currentUrl = new URL(window.location.href);
 var finishUrl = new URL("/myfinishpage/", window.location.origin);
 finishUrl.searchParams.set("utm_source", currentUrl.searchParams.get("utm_source"));
 // ... etc.
 Iteras.orderingiframe({
   "profile": "myprofile",
   "orderingid": "XXXXXX",
   "next": finishUrl.href
})

# Reading order data on the finished page

Data about the order can be useful on the finished page: An order ID to deduplicate conversions on, the customer's name for a personal greeting, or a signal for your content system to react to. The ordering form can append this to the redirect as an encrypted token in the iteras-order-data GET parameter - the token format and how to decode it are described under order data on the redirect.

The token is decoded on your server, so the flow is as follows: The request for the finished page carries the parameter, your server decodes it and renders the page with the order data, and the page fires the analytics events - under your consent handling, since it is your page.

For more detail than you want to put in the redirect - the ordered products and their prices, for example - include the order ID field and look the order up through the orders API:

GET /api/orders/?order_id=83529&fields=data,invoice_lines HTTP/1.1

The order ID is also the stable key for joining browser-side conversions with the API data later.

# Adding analytics scripts to the Iteras pages

The code customization fields can also carry an analytics snippet directly, so page views and events are collected inside the ordering and self-service pages themselves, without wiring on the embedding page.

Consent needs particular attention here. The Iteras pages are a separate document on an Iteras domain unless you set up a custom domain, so a consent choice stored on your site is not visible inside them, and a snippet added without a guard runs for every visitor. Inject a script this way only if it may run without consent (e.g. a cookieless, consent-exempt counter) or you can give the pages a consent signal they can actually read.

The latter works when the pages are served on a custom domain, i.e. a subdomain of your site. A consent cookie set for the whole domain - as the common consent platforms do - is readable inside the iframe, and the snippet can check it before initializing.

When the consent state only exists on your own pages, send events out of the iframe as described above instead, and decide on your page what to forward.

# Counting orders server-side

Browser-based tracking may be imprecise due to ad blockers, declined consent, a tab closed before the finished page loaded, etc. When the numbers have to be complete, read the orders from the orders API periodically, with created_after set around the last run, and reconcile against what the browser reported - the order ID from the redirect data is the join key. For a continuous feed of customer and subscription changes, set up webhooks as described in the synchronization guide.

← Identity and access management