QL SDK - Server to Server

Instead of installing our JS SDK on your product and payment confirmation pages, you may send us product and payment confirmation events from your backend to our server-to-server SDK events API endpoint.

This kind of integration is more suitable in situations when you're unable to embed our JS SDK in your pages, or when you want to have stricter control over what data is sent to QL.

Sending SDK events

Server-to-server SDK events should be sent to https://sdk-events.quicklizard.com/events as an HTTP POST request.

SDK events should be send from your backend in product and payment confirmation pages. Please be sure to read our current SDK docs where you can learn about which data should be sent in each page type.

This part of our SDK docs only covers the server-to-server integration and assumes you are familiar with other concepts of using our SDK.

Product Page View Events

The structure of a single product page view event payload is as follows:

{
  "client_key": "YOUR_CLIENT_KEY", //your QL client key
  "price": 123.41, //product shelf price as float
  "product_id": "123-AA-X23", //product identifier string
  "event": "view", //event name - "view" represents a product page view
  "permalink": "https://yourstore.com/123-AA-X23/", // product URL on your store
  "vid": "DASDAS-#CCCC-NA", //optional anonymous user identifier
  "tags": ["user:new"], //optional tags for this evening
  "channels": ["online"] //optional pricing channels for this event
}

Please Note

  • The vid field is completely optional and is used internally by QL as part of our analytics algorithms.
  • All other fields are required
  • The price field must be a valid float
  • The product_id is the product's unique identifier (uid)

Product Conversion Events

The structure of a single product payment confirmation event payload is as follows:

{
  "client_key": "YOUR_CLIENT_KEY", //your QL client key
  "price": 123.41, //product sale price as float
  "product_id": "123-AA-X23", //product identifier string
  "event": "conversion", //event name - "view" represents a product page view
  "vid": "DASDAS-#CCCC-NA", //optional anonymous user identifier
  "tags": ["user:new"], //optional tags for this evening
  "channels": ["online"], //optional pricing channels for this event
  "units": 3 // optional number of sold units
}

Please Note

  • The vid field is completely optional and is used internally by QL as part of our analytics algorithms.
  • All other fields are required
  • The price field must be a valid float and contain the total sale price of a given product (in case of multiple sold units, the value should be cost/unit X units)
  • The product_id is the product's unique identifier (uid),
  • Conversion event channels field should only contain a single channel, despite being passed as an array
  • The units field is optional - It can be used to specify the number of sold units

API Request format

The server-to-server API supports sending one or more events, as an array of JSON objects, as described above.

For example, in your product page, you will send an HTTP POST request for a single page-view event:

curl -XPOST https://sdk-events.quicklizard.com/events -d '[{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 123.41,
  "product_id": "123-AA-X23",
  "event": "view",
  "permalink": "https://yourstore.com/123-AA-X23/",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"]
}]'

In the payment confirmation page, you might have more than one product that was bought, and therefore will send multiple conversion events:

curl -XPOST https://sdk-events.quicklizard.com/events -d '[{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 123.41,
  "product_id": "123-AA-X23",
  "event": "conversion",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"]
},
{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 60,
  "product_id": "455DD-AA-X23",
  "event": "conversion",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"],
  "units": 3
}]'

Please Note

The POST payload is a JSON-formatted array of event objects. In the above example, the second event specifies a units value of 3, meaning 3 units of that product were sold. In that case, the price field contains the total paid price for 3 units (eg. if one unit costs 10EU the price field will be 30, which is 3 units X 10EU per unit).

API Response Format

The API will respond with a JSON containing 3 array fields for processed events, failed events and processing errors.

  • processed - events that were successfully parsed and sent to our backends
  • failed - events that were not parsed due to errors in event structure
  • errors - event parse errors
{
  "processed": [{...}],
  "failed": [{...}],
  "errors": [{...}]
}