Sale conversion tracking

After this guide, you will know how to create and send sale tracking requests to Linkster. It is highly recommended that you read the overview to tracking methods first.

Sale conversion tracking should be used for tracking sales made in your web store. This tracking method will not only track a total turnover, but also the shopping basket of an order, which results in greater tracking insights.

caution

The user tracking container must be installed first before you can start tracking sales with Linkster.

Endpoint

A sale conversion tracking request must be made to this endpoint:

https://trck.linkster.co/trck/ebasket/

note

The sale conversion tracking endpoint requires a trailing slash (/ebasket/).

Endpoint parameters

All parameters must be passed as URL parameters to the sale conversion tracking request:

URL parameter	Required	Description
`json`	required	The shopping basket array.
`campaign_id`	required	The Linkster campaign ID of your site/web store. Must be the same value as you have used for the user tracking container.
`currency`	required	Three character ISO 4217 currency code of the sale. E.g. `EUR` or `USD`.
`order_category`	optional	An optional category string to group sales.
`vc`	optional	Cleaned voucher code string.

Basket

The basket object is a stringified JSON array containing all line item objects of the order.

Line item object

A line item object must contain the following keys:

Key name	Type	Example value	Description
campaign_id	`integer`	19	The Linkster campaign ID of your site/web store. Must be the same value as you have used for the user tracking container.
attribution	`integer`	1	Attribution settings (Is always 1 unless otherwise communicated by Linkster).
emid	`string`	exampleEMID00000001	EMID value stored in `localStorage` or `document.cookie`. Can be set to an empty string if no emid is present. Read more about on how to access the EMID value here.
trigger_id	`integer`	1 or 2	Categorizes the order's customer. Choose `1` for default customer or `2` for new customer.
token	`string`	1001	Order ID or order number of the order. This ID is used to match existing transactions in Linkster and is displayed to the user in the transaction analyses.
article_number	`string`	3141592	The ID of the product or an identifier string.
productname	`string`	Linkster T-Shirt	The name of the product.
category	`string`	Clothing	The product's category. Can be set to an empty string if no category is present.
amount	`integer`	1 2 9999 ...	The product's amount or quantity for this order.
price	`string`	-1.49 0 9.99 ...	The signed net price of the single product. Can also be negative to reflect discounts or taxes.

Here is an example for pushing a normal product to the basket:

...

var basket = [];

basket.push(
  {
    "campaign_id": 19,
    "token": "1001",
    "trigger_id": 1,
    "article_number": "3141592",
    "productname": "Linkster T-Shirt",
    "category": "Clothing",
    "amount": 1,
    "price": "29.99",
    "attribution": 1,
    "emid": "exampleEMID00000001"
  }
);

...

Reflecting taxes (VAT) and discounts

Taxes and discounts can either be directly deducted from each product price or be pushed as a negative priced line item to the basket array. You can pick the method that is easiest for you.

Linkster advises to first subtract any discount from the gross price and then subtract any taxes (VAT). Example:

You sold a T-Shirt in your online store for 29.99 EUR and the customer applied the voucher code "SAVE10" for 10 % discount. Your store and customer lives in Germany where 19 % VAT accrue. You should calculate the finale price you sent to Linkster as follows:

Subtract the 10 % discount from the product price: 29.99 EUR * 0.9 ≈ 26.99 EUR.
Subtract 19 % VAT from the discounted price: 26.99 EUR / 1.19 ≈ 22.68 EUR.

The final price you send to Linkster for this line item should be: 22.68.

If you want to deduct taxes as a single line item, you can push the following item to the basket array:

...

var basket = [];

basket.push(
  {
    "campaign_id": 19,
    "token": "1001",
    "trigger_id": 1,
    "article_number": "taxes",
    "productname": "taxes",
    "category": "taxes",
    "amount": 1,
    "price": "-4.31",
    "attribution": 1,
    "emid": "exampleEMID00000001"
  }
);

...

And to deduct discounts:

...

var basket = [];

basket.push(
  {
    "campaign_id": 19,
    "token": "1001",
    "trigger_id": 1,
    "article_number": "discount",
    "productname": "discount",
    "category": "discount",
    "amount": 1,
    "price": "-3",
    "attribution": 1,
    "emid": "exampleEMID00000001"
  }
);

...

caution

You should always send net prices with deducted discounts to Linkster, otherwise some analytics will lose their correctness.

Preparing the basket

Before you can append the basket to the tracking request, you must prepare it so, that it can be safely sent to Linkster.

The preparation consists of two steps:

Stringifying the basket array to JSON
URL encoding the stringified basket

In code, this would look like:

...

var basket = [
  {
    "campaign_id": 19,
    "token": "1001",
    "trigger_id": 1,
    "article_number": "3141592",
    "productname": "Linkster T-Shirt",
    "category": "Clothing",
    "amount": 1,
    "price": "29.99",
    "attribution": 1,
    "emid": "exampleEMID00000001"
  }
];

// stringifying the basket (Step 1)
var basket = JSON.stringify(basket);
// URL encoding the basket (Step 2)
basket = encodeURIComponent(basket);

// the `basket` is now ready to be appended to the tracking request
var url = "https://trck.linkster.co/trck/ebasket/";
url += "?json=" + basket;

...

(Optional) Providing a total turnover

Normally, you should not pass a total turnover to a sale conversion tracking request, because Linkster will automatically calculate it based on the basket.

However, sometimes it may not be possible for you to pass individual line item prices to Linkster. In this case, you can overwrite the individual line item prices with the total_turnover URL parameter. Instead of calculating the total turnover based on the basket, Linkster will then just use your provided value.

Example:

...

var url = "https://trck.linkster.co/trck/ebasket/";
url += "?json=" + basket;
...
url += "&total_turnover=29.99";

...

The value of total_turnover should be an integer or a float (with a decimal point).

danger

Passing the total_turnover to a sale conversion request (and thus overwrite the default logic) should only be used as a last resort.

Example integration

With the gained knowledge, we are now ready to write an integration that will track sale conversions, including their shopping baskets and line items.

The following code offers valid and full-featured sale conversion tracking for Linkster:

var trackSale = function (orderId, products, discount, taxes, currency, voucherCode, triggerId, orderCategory) {
  // getting the EMID value
  var cookieEmid = document.cookie.match(/emid\=([a-zA-Z0-9\-\_]+)/i);
  var emid = window.localStorage['emid'] || (cookieEmid === null || cookieEmid === void 0 ? void 0 : cookieEmid[1]);
  
  // setting sale track params
  var campaignId = 19;
  var basket = [];

  // pushing each product to the basket array.
  products.forEach((product) => {
    basket.push({
      "campaign_id": campaignId,
      "token": orderId,
      "trigger_id": triggerId,
      "article_number": product.id,
      "productname": product.name,
      "category": product.category,
      "amount": product.amount,
      "price": product.price,
      "attribution": 1,
      "emid": emid
    })
  });

  /**
   * in this example we don't deduct the discount directly from the product prices 
   * but rather push the complete discount value as a negative priced line item into the basket.
   */
  basket.push({
    "campaign_id": campaignId,
    "token": orderId,
    "trigger_id": triggerId,
    "article_number": "discount",
    "productname": "discount",
    "category": "discount",
    "amount": 1,
    "price": discount,
    "attribution": 1,
    "emid": emid
  });

  /**
   * we also push the collected taxes (VAT) as a negative priced line item into the basket,
   * so that Linkster can later calculate the total net turnover of the order.
   */
  basket.push({
    "campaign_id": campaignId,
    "token": orderId,
    "trigger_id": triggerId,
    "article_number": "taxes",
    "productname": "taxes",
    "category": "taxes",
    "amount": 1,
    "price": taxes,
    "attribution": 1,
    "emid": emid
  });

  var url = "https://trck.linkster.co/trck/ebasket/";
  url += "?json=" + encodeURIComponent(JSON.stringify(basket)); // stringifying and encoding the basket in one line of code.
  url += "&campaign_id=" + campaignId;
  url += "&currency=" + currency;
  url += "&order_category=" + orderCategory;
  url += "&vc=" + encodeURIComponent(voucherCode);

  var req = new XMLHttpRequest();
  req.withCredentials = true;
  req.open("GET", url);
  req.send();
}

// we are now ready to track an order:
var products = [
  {
    id: "3141592",
    name: "Linkster T-Shirt",
    category: "Clothing",
    amount: 2,
    price: "29.99",
  },
  {
    id: "1618033",
    name: "Linkster Hoodie",
    category: "Clothing",
    amount: 1,
    price: "59.99",
  }
];

trackSale(
  "1001", // order id 
  products, 
  "-12.00", // total discount, rounded to second decimal figure
  "-17.24", // total taxes, rounded to second decimal figure
  "EUR", // currency
  "SAVE10", // applied voucher code or empty string 
  1, // trigger id. (2 = new customer)
  "" // order category
);

info

You can adopt the code from above if you are writing your own integration.

Existing integrations

Linkster provides integrations for popular technologies that will enable full-featured sale conversion tracking with minimal to no code changes needed from your side.

A list of all existing integrations can be found here.

Sale conversion tracking

Endpoint​

Endpoint parameters​

Basket​

Line item object​

Reflecting taxes (VAT) and discounts​

Preparing the basket​

(Optional) Providing a total turnover​

Example integration​

Existing integrations​