How to set up a full Server-side Hybrid Universal Integration

Last updated: 2024-09-26

There are 3 steps to complete the integration.

Step 1: Send orders to ProfitMetrics serverside

Step 2: Install the Server-side Hybrid Universal Integration script

Step 3: Create a Product Feed for ProfitMetrics

Important information when Migrating from Client-side Universal Integration to Server-side Hybrid Universal Integration

If you are migrating from a Universal Integration, the previous scripts called pmOriginTrack and pmLogOrder need to be removed.

Part 1: Send orders to ProfitMetrics serverside

Send orders to the following endpoint as a GET request.

https://my.profitmetrics.io/l.php

Add the following parameters

Parameter	Description	Nortes
v	Version	Required - Must be set to ”3uh”
pid	Website Public ID	Required
o	Orderspec, JSON object containing order data	Required - Must be URL-encoded

IMPORTANT: If your specific checkout process means that the user will only be identified on the order confirmation page (such as if using stripe checkout, or something similar), it is essential that the order is not transmitted until after the order confirmation page has loaded and sent the identify event to ProfitMetrics (setEmail). As a general rule of thumb, waiting 5 minutes to transmit the order would suffice."

Build the Orderspec JSON object.

While some fields are REQUIRED and others are RECOMMENDED, we strongly recommend filling out as many as possible. Any missing fields will directly limit functionalities within ProfitMetrics.

Any fields that are not filled, should be omitted from the orderspec object, or set to null. They can not be empty or undefined.

Field name	Type	Description	Notes
id	String	Unique order id	Required
ts	Number	Unix timestamp (UTC), second resolution	Required
orderEmail	String	Customer email	*Required 1**
orderEmailMD5	String	Customer email, sha256 hashed. It is vital that the email must be trimmed and lowercased BEFORE hashing.	*Required 1**
orderEmailSHA256	String	Customer email, sha256 hashed. It must be lowercased and trimmed, and the part before ’@’ must be stripped of any dots(.) if the domain part is googlemail.com or gmail.com. Example: ” John.Mcafee@gmail.com” would be preprocessed to ”johnmcafee@gmail.com”, and then hashed	*Required 1**
orderEmailSHA256GA	String	Customer email, sha256 hashed. It is vital that the email must be trimmed and lowercased BEFORE hashing.	*Required 3**
customerPhone	String	Customer phone number. There must be no letters or whitespaces, and it must include the countrycode number, area codes, and actual phone number. For example: ”16505551212” for a north american phone number, or ”4542504250” for a danish phone number	Recommended
customerPhoneMD5	String	md5 hashed version of customerPhone	*Recommended 2**
customerPhoneSHA256	String	sha256 hashed version of customerPhone	*Recommended 2**
shippingMethod	String	Shipping method name	Required
shippingCountry	String	Should be in ISO 3166-1 alpha-2 format	Recommended
shippingZipcode	String	Destination zipcode	Recommended
shippingWeight	Number	Weight in grams	Recommended
paymentMethod	String	Payment method name	Required
currency	String	Format is 3 letter ISO 4217. Examples: “DKK”, “EUR”	Recommended
voucherCode	String	gift/voucher code used	Optional
priceShippingExVat	Number	The charged price for shipping, excl VAT	Recommended
priceTotalExVat	Number	Total charged/paid price, excluding VAT	Required
priceTotalInclVat	Number	otal charged/paid price, including VAT	Required
products	Array	Array of objects	Required
overrides	Object	Contains overrides on the order level. See Override table below.	NEW - Optional

Order overrides

Order overrides allows you to manually override shipping cost, payment cost, extra cost like Packaging and handeling as well as the actual gross profit.

Any fields that are not filled, should be omitted from the orderspec object. They can not be empty or undefined.

Field name	Type	Description	Notes
shippingCostExVat	Number	Used to send / overwrite Shipping cost. IMPORTANT: Value must be excluding VAT / Tax.	NEW - Optional
paymentCostExVat	Number	Used to send / overwrite Payment cost. (IMPORTANT: Value must be excluding VAT / Tax)	NEW - Optional
extraCostExVat	Number	Used to send / overwrite Packaging and handling cost or any extra expense to be deducted. IMPORTANT: Value must be excluding VAT / Tax.	NEW - Optional
grossProfitExVat	Number	Used to send / overwrite the Gross Profit. IMPORTANT: Value must be excluding VAT / Tax.	NEW - Optional

*1: The orderEmail is required, either in plaintext or hash. If plaintext is supplied, hashes do not need to be submitted. If plaintext is left out, then both md5 and sha256 hash of the email must be submitted

*2 Its optional to provide the customer phone number, but if it is provided, either simply the customerPhone field should be provided, or both customerPhoneMD5 and customerPhoneSHA256

*3 This should not be supplied if plaintext orderEmail is supplied. In case it is not, we strongly recommend supplying this, or some features will be much less precise(Google Ads enhanced conversions) *4 While it is possible to operate without this data, it severely limits functionality, so we very strongly recommend to send these fields unless it is absolutely not possible

*4 While it is possible to operate without this data, it severely limits functionality, so we very strongly recommend to send these fields unless it is absolutely not possible.

Products array objects contains the following fields:

Field name	Type	Description	Remarks
sku	String	IMPORTANT: The product "sku" DOES NOT necessarily refer to the actual SKU but needs to match the product "id" in the product feed containing product cost. This can either be the internal product variant id of your e-commerce platform, the EAN or the actual SKU. Check with your product feed to determine the correct value. It must not be an empty string.	Required
qty	Number	Quantity	Required
priceExVat	Number	Unit price excluding VAT	Required
overrides	Object	Contains overrides on the product level. See Override table below.	NEW - Optional

Product overrides

Product overrides allows you to manually override Cost Price, Title, Brand, Category, Google Product Category ID and Google Product Category EN.

Any fields that are not filled, should be omitted from the orderspec object. They can not be empty or undefined.

Field name	Type	Description	Remarks
unitCostPriceExVat	Number	Used to send / overwrite product cost. IMPORTANT: Value must be excluding VAT / Tax.	NEW - Optional
title	String	Used to send / overwrite product title.	NEW - Optional
brand	String	Used to send / overwrite product brand.	NEW - Optional
categories	Array	Used to send the product category	NEW - Optional
googleProductCategoryId	String	Used to send the Google Product Category ID	NEW - Optional
googleProductCategoryEN	String	Used to send the Google Product Category EN	NEW - Optional

Example json orderspec WITHOUT OVERRIDES:

{
   "id": "12430345",
   "ts": 1616595095,
   "orderEmail": "test@profitmetrics.io",
   "customerPhone": "4542504250",
   "shippingMethod": "UPS Nextday",
   "shippingCountry": "Denmark",
   "shippingZipcode": "7400",
   "shippingWeight": 2500,
   "paymentMethod": "Stripe",
   "currency": "DKK",
   "voucherCode": "FREESHIPPING",
   "priceShippingExVat": 0,
   "priceTotalExVat": 100,
   "priceTotalInclVat": 125,
   "products": [
      {
         "sku": "123431-12",
         "qty": 1,
         "priceExVat": 50,
      },
      {
         "sku": "123431-13",
         "qty": 1,
         "priceExVat": 50,
      }
   ]
}

Example json orderspec WITH OVERRIDES;

{
  "id": "12430345",
  "ts": 1616595095,
  "orderEmail": "test@profitmetrics.io",
  "customerPhone": "4542504250",
  "shippingMethod": "UPS Nextday",
  "shippingCountry": "Denmark",
  "shippingZipcode": "7400",
  "shippingWeight": 2500,
  "paymentMethod": "Stripe",
  "currency": "DKK",
  "voucherCode": "FREESHIPPING",
  "priceShippingExVat": 0,
  "priceTotalExVat": 100,
  "priceTotalInclVat": 125,
  "overrides":{
    "shippingCostExVat": 29,
    "paymentCostExVat": 1.8,
    "extraCostExVat": 5,
    "grossProfitExVat": 30
   },
   "products": [
        {
        "sku": "123431-12",
        "qty": 1,
        "priceExVat": 50,
        "overrides":{
            "unitCostPriceExVat": 4,
            "title": "Product Title",
            "brand": "Brand name",
            "categories": ["Category 1", "Category 1"],
            "googleProductCategoryId": 1,
            "googleProductCategoryEN": "Animals & Pet Supplies"
            }
        },
        {
        "sku": "123431-12",
        "qty": 1,
        "priceExVat": 50,
        "overrides":{
            "unitCostPriceExVat": 4,
            "title": "Product Title",
            "brand": "Brand name",
            "categories": ["Category 1", "Category 1"],
            "googleProductCategoryId": 200,
            "googleProductCategoryEN": "Apparel & Accessories > Jewelry > Rings"
            }
        }
    ]
}

Final GET request should look like this.

https://my.profitmetrics.io/l.php?v=3uh&pid=XXXXXXXXXXXXXXXX&o={"id":"XXXX","ts":1679476010,"orderEmail":"example@example.com","customerPhone":"00000000","shippingMethod":"SHIPPING","shippingCountry":"DK","shippingZipcode":"0000","shippingWeight":0000,"paymentMethod":"PAYMENTMETHOD","currency":"EUR","priceShippingExVat":0,"priceTotalExVat":100.00,"priceTotalInclVat":125.00,"products":[{"sku":"PRODUCT-ID","qty":1,"priceExVat":100.00},{"sku":"PRODUCT-ID","qty":1,"priceExVat":0}]}

Congratulations on completing Part 1!

Part 2 - Install the Serverside Hybrid integration one of two ways: