API documentation - Data Management Platform

Tracking events

There are two ways to track data: Through front-end or back-end.
Front-end means that you will use a tracking pixel on your website. Back-end means you use server to server communication to track your data via our API.

The goal is to send events to us with user behavior, so we can create segments that you can use on the connected channels.
This integration guide will help you set up the event tracking.

Front-end tracking

Almost all tracking will be done through front-end.

Place the following personalized code snippet in the head section of every page you want to use tracking on.

NOTE: Please log in to see your personalized snippet.


    <script type="text/javascript">

    (function(s,q,u,e,z,l,y){s['SqueezelyObject']=z;s[z]=s[z]||function(){
    (s[z].q=s[z].q||[]).push(arguments)},s[z].l=1*new Date();l=q.createElement(u),
    y=q.getElementsByTagName(u)[0];l.async=1;l.src=e;y.parentNode.insertBefore(l,y)
    })(window,document,'script','https://squeezely.tech/tracker/<YOUR_IDENTIFIER>/sqzl.js','sqzl');

    </script>

You can track Standard Events or Custom Events.
For example. if you want to track a pageview through the standard PageView event, use the following code:


    <script type="text/javascript">

        sqzl({
            "event" : "PageView"
        });

    </script>

That's all, your visitors are now being tracked!
Ofcourse, the more info we have the better your segments will be. To provide more data, use the available properties as shown in the documentation of the event.

Another example: Track a Purchase event:


<script type="text/javascript">

    sqzl({
        "event"         : "Purchase",
        "email"         : "jan@schmit.com",
        "firstname"     : "Jan",
        "lastname"      : "Schmidt",
        "gender"        : "M",
        "birthdate"     : "1985-12-31",
        "city"          : "Berlin",
        "country"       : "DE",
        "orderid"       : "12345",
        "currency"      : "EUR",
        "products"      : [
                            "id": "ABC123",
                            "name": "Product 1",
                            "category_id": "CAT_1",
                            "price": 29.99,
                            "quantity": 2
                          ]
    });

</script>

All events work this way, you can track as many events on a page as you want. Use the left menu to see which properties you can use with which events.

Event: PageView

Event should be fired when someone views a page.
Note: This event must be implemented on all pages, regardless if other events are triggered.

Available properties:

Name	Description
event	PageView	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session.	Optional

Event: Purchase

Event should be fired when someone makes a purchase.

Available properties:

Name Description

event Purchase Mandatory

email Customer email Mandatory

orderid Order reference of the purchase. Used to calculate revenue correctly. Mandatory

firstname Customer firstname Mandatory

lastname Customer lastname Mandatory

userid User id or username of the customer. Your unique identifier for the customer. Optional

campaign The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session. Optional

source Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session. Optional

gender Customer gender (M/F/U) Optional

birthdate Customer birthdate (yyyy-mm-dd) Optional

phone Customer phone Optional

postcode Customer postcode Optional

city Customer city Optional

country Customer 2-letter country code (eg. NL, ISO 3166-1 alpha-2) Optional

salelocation Where is a purchase made (online/offline) Optional

offlinelocation Identifier of physical store location Optional

currency Currency of the purchase (e.g. GBP/EUR/USD) Optional

newsletter Is the user opt-in for email/newsletter. Correct value are yes or no. Optional

products

JSON array of product(s). Supported properties:

id	unique id or SKU. Required.
name	name of the product
price	Price of the single product, 2 decimals. Required.
quantity	Quantity bought. Defaults to 1.

Example 1:

  {"id": "ABC123", "price": 29.99}

Example 2:

[
    {
        "id": "ABC123",
        "name": "Product 1",
        "price": 29.99,
        "quantity": 2
    },
    {
        "id": "XYZ_789",
        "name": "Product 2",
        "price": 39.99,
        "quantity": 1
    }
]

Mandatory

Event: PrePurchase

Fire the PrePurchase event when a user has shared details with you, but still has to confirm the payment.
For example fire the event just before a customer is redirected to an external payment environment.

Note: The PrePurchase event is not mandatory, however we highly recommend using it. Implementing this event will give you more accurate sales tracking and more complete profile information.

Available properties:

Name Description

event PrePurchase Mandatory

campaign The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session. Optional

source Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session. Optional

email Customer email Mandatory

userid User id or username of the customer. Your unique identifier for the customer. Optional

firstname Customer firstname Mandatory

lastname Customer lastname Mandatory

gender Customer gender (M/F/U) Optional

birthdate Customer birthdate (yyyy-mm-dd) Optional

phone Customer phone Optional

postcode Customer postcode Optional

city Customer city Optional

country Customer 2-letter country code (eg. NL, ISO 3166-1 alpha-2) Optional

salelocation Where is a purchase made (online/offline) Optional

offlinelocation Identifier of physical store location Optional

orderid Order reference of the purchase. Used to calculate revenue correctly. Optional

currency Currency of the purchase (e.g. GBP/EUR/USD) Optional

newsletter Is the user opt-in for email/newsletter. Correct value are yes or no. Optional

products

JSON array of product(s). Supported properties:

id	unique id or SKU. Required.
name	name of the product
price	Price of the single product, 2 decimals. Required.
quantity	Quantity bought. Defaults to 1.

Example 1:

  {"id": "ABC123", "price": 29.99}

Example 2:

[
    {
        "id": "ABC123",
        "name": "Product 1",
        "price": 29.99,
        "quantity": 2
    },
    {
        "id": "XYZ_789",
        "name": "Product 2",
        "price": 39.99,
        "quantity": 1
    }
]

Mandatory

Event: AddToCart

Event should be fired when someone adds something to their cart.

Available properties:

Name Description

event AddToCart Mandatory

campaign The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session. Optional

source Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session. Optional

currency Currency of the product (e.g. GBP/EUR/USD) Optional

products

JSON array of product(s). Supported properties:

id	unique id or SKU. Required.
name	name of the product
category_id	Unique id or SKU of the category
price	Price of the single product, 2 decimals. Required.
quantity	Quantity added to cart. Defaults to 1.

Example 1:

  ["id": "ABC123"]

Example 2:

[
    {
        "id": "ABC123",
        "name": "Product 1",
        "category_id": "CAT_1",
        "price": 29.99,
        "quantity": 2
    },
    {
        "id": "XYZ_789",
        "name": "Product 2",
        "category_id": "CAT_2",
        "price": 39.99,
        "quantity": 1
    }
]

Mandatory

Event: ViewContent

Event should be fired when someone visits a product page on your website.

Available properties:

Name Description

event ViewContent Mandatory

campaign The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session. Optional

source Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session. Optional

currency Currency of the product (e.g. GBP/EUR/USD) Optional

products

JSON array of product(s). Supported properties:

id	unique id or SKU. Required.
name	name of the product.
category_id	Unique id or SKU of the category.
price	Price of the single product, 2 decimals.

Example 1:

  [{"id": "ABC123"}]

Example 2:

[{
    "id": "ABC123",
    "name": "Product 1",
    "category_id": "CAT_1",
    "price": 29.99
}]

Mandatory

Event: ViewCategory

Event should be fired when someone views a category page.

Available properties:

Name	Description
event	ViewCategory	Mandatory
category_id	Id of the viewed category (e.g. ABC123)	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session.	Optional
objectname	Name of the viewed category	Optional

Event: Search

Event should be fired when someone searched for something on your website.

Available properties:

Name	Description
event	Search	Mandatory
keyword	Search keyword	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session.	Optional

Event: Custom

You can add a custom event to target people with certain website behavior.

Available properties:

Name	Description
event	Your custom event	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session.	Optional
value	Value of your custom event	Optional

Event: Custom

You can add a custom event to target people with certain website behavior.

Available properties:

Name	Description
event	Lead	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session.	Optional
value	Value of your lead event	Optional

Event: EmailOptIn

Event should be fired when someone subscribes to or unsubscribes from your newsletter.

Available properties:

Name	Description
event	EmailOptIn	Mandatory
email	Customer email	Mandatory
newsletter	Is the user opt-in for email/newsletter. Correct value are yes or no.	Mandatory

Event: CompleteRegistration

Event should be fired when someone completes a registration/signup form.

Available properties:

Name	Description
event	CompleteRegistration	Mandatory
campaign	The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you don't have to pass this. Saved in client session.	Optional
source	Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you don't have to pass this. Saved in client session.	Optional

Tracking through back-end

With backend tracking you can send events through backend.
Backend events have the same parameters as frontend events, but also allow you to set the date & time.
You can send up to 250 events at a time. See the PHP example code below:



    $url = "https://squeezely.tech/api/v1/track";
    $fields = [
        "events" => [
                        [
                            "event"         => "Purchase",
                            "email"         => $email,
                            "firstname"     => $firstname,
                            "lastname"      => $lastname,
                            "gender"        => $order->getCustomerGender(),
                            "birthdate"     => $order->getCustomerDob(),
                            "phone"         => $order->getShippingAddress()->getTelephone(),
                            "postcode"      => $order->getShippingAddress()->getPostcode(),
                            "city"          => $order->getShippingAddress()->getCity(),
                            "country"       => $order->getShippingAddress()->getCountry(),
                            "currency"      => $order->getOrderCurrencyCode(),
                            "orderid"       => $orderId,
                            "newsletter"    => $newsletterOptin ? "yes" : "no",
                            "products"      => [
                                    [
                                        "id" => "ABC123",
                                        "name" => "Product 1",
                                        "category_id" => "CAT_1",
                                        "price" => 29.99,
                                        "quantity" => 2
                                    ],
                                    [
                                        "id" => "XYZ_789",
                                        "name" => "Product 2",
                                        "category_id" => "CAT_2",
                                        "price" => 39.99,
                                        "quantity" => 1
                                    ]
                                ]
                        ]
                ]
        ];
    $json = json_encode($fields);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'X-AUTH-ACCOUNT: <ACCOUNT_IDENTIFIER>',
        'X-AUTH-APIKEY: <API_KEY>',
        'Content-Type: application/json',
        'Content-Length: ' . strlen($json)
        ));

    $result = curl_exec($ch);
    curl_close($ch);

NOTE: Please log in to see your Account-identifier and API Key.

Just replace the values with your values and you're ready to go!

Response values

When correctly authorized, we will return a json response with the result.

Example response for a correct call:

{
    "success": true,
    "count": 12,
    "errors": []
}

Example response for an incorrect call:

{
    "success": false,
    "count": 0,
    "errors": [
        "NO_EMAIL_OR_USERID"
    ]
}

Response codes

HTTP status code	Description	Error codes
201	Resource created (partially)	NO_EMAIL_OR_USERID NO_MERCHANT UNKNOWN_ERRROR
400	No resource created	NO_EVENTS TOO_MANY_EVENTS NO_EMAIL_OR_USERID NO_MERCHANT UNKNOWN_ERRROR
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Event: Purchase

Event should be fired when someone makes a purchase.

Available properties:

Name Description

event Purchase Mandatory

email Customer email Mandatory

firstname Customer firstname Mandatory

lastname Customer lastname Mandatory

orderid Order reference of the purchase. Used to calculate revenue correctly. Mandatory

timestamp Timestamp of the event, only needed for events in the past. Formats allowed: unix epoch timestamp or yyyy-mm-dd Optional

userid User id or username of the customer. Your unique identifier for the customer. Optional

gender Customer gender (M/F/U) Optional

birthdate Customer birthdate (yyyy-mm-dd) Optional

phone Customer phone Optional

postcode Customer postcode Optional

city Customer city Optional

country Customer 2-letter country code (eg. NL, ISO 3166-1 alpha-2) Optional

salelocation Where is a purchase made (online/offline) Optional

offlinelocation Identifier of physical store location Optional

currency Currency of the purchase (e.g. GBP/EUR/USD) Optional

newsletter Is the user opt-in for email/newsletter. Correct value are yes or no. Optional

products

Array of product(s). Supported properties:

id	unique id or SKU. Required.
name	name of the product
price	Price of the single product, 2 decimals. Required.
quantity	Quantity bought. Defaults to 1.

Example 1:

  ["id" => "ABC123", "price" => 29.99]

Example 2:

[
    [
        "id" => "ABC123",
        "name" => "Product 1",
        "price" => 29.99,
        "quantity" => 2
    ],
    [
        "id" => "XYZ_789",
        "name" => "Product 2",
        "price" => 39.99,
        "quantity" => 1
    ]
]

Mandatory

campaign The identifier for this campaign. If this is in the url of your landing page as variable sqzl_campaign or utm_campaign, you can omit this. Saved in client session. Optional

source Source of the customer (e.g. facebook or adwords). If this is in the url of your landing page as variable sqzl_source or utm_source, you can omit this. Saved in client session. Optional

Response codes

HTTP status code	Description	Error codes
201	Resource created (partially)	NO_EMAIL_OR_USERID NO_MERCHANT UNKNOWN_ERRROR
400	No resource created	NO_EVENTS TOO_MANY_EVENTS NO_EMAIL_OR_USERID NO_MERCHANT UNKNOWN_ERRROR
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Reporting

You can the export data you collected with Squeezely.
Call the resource endpoint and we will generate a CSV file.
Optionally you can supply a callback url which we call when the file is generated.
CSV files are purged after 7 days.

Example request:



    $url = "https://squeezely.tech/api/v1/reporting/events";
    $fields = [
        "from"         => "2018-01-01",
        "to"         => "2018-02-01"
    ];
    $json = json_encode($fields);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($fields));
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'X-AUTH-ACCOUNT: <ACCOUNT_IDENTIFIER>',
        'X-AUTH-APIKEY: <API_KEY>',
        'Content-Type: application/json',
        'Content-Length: ' . strlen($json)
    ));
        
    $result = curl_exec($ch);
    curl_close($ch);

Example response:

{
    "success": true,
    "url": "https://squeezely.tech/api/v1/reporting/download/cf2acd31eac8c5288f05dd6366dc1e4f.csv"
}

Response codes

HTTP status code	Description	Error codes
201	Resource created
400	No resource created	REPORTING_NOT_ENABLED, UNKNOWN_ERROR
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Events export

Endpoint: /api/v1/reporting/events

You can use these filters:

Name	Description
from	YYYY-mm-dd or Unix epoch timestamp.	Mandatory
to	YYYY-mm-dd or Unix epoch timestamp.	Mandatory
custom_fields	Whether to export custom fields. Correct value are yes or no. Defaults to yes	Optional
callback_url	Url we call once when the file is available for download.	Optional

Response codes

HTTP status code	Description	Error codes
201	Resource created
400	No resource created	REPORTING_NOT_ENABLED, UNKNOWN_ERROR, NO_DATE_RANGE_PROVIDED, INVALID_FROM_DATE, INVALID_TO_DATE
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Customers export

Endpoint: /api/v1/reporting/customers

You can use these filters:

Name	Description
userids	Comma separated list of your unique user identifier(s) of the customers you want to select.	Optional
emails	Comma separated list of emails of the customers you want to select.	Optional
custom_fields	Whether to export custom fields. Correct value are yes or no. Defaults to yes	Optional
callback_url	Url we call once when the file is available for download.	Optional

Response codes

HTTP status code	Description	Error codes
201	Resource created
400	No resource created	REPORTING_NOT_ENABLED, UNKNOWN_ERROR
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Download an export

Endpoint: /api/v1/reporting/download/XXX.csv

Use this endpoint to download a previously created report.

Response codes

HTTP status code	Description	Error codes
200	OK
404	Resource not available	RESOURCE_NOT_FOUND, RESOURCE_NOT_READY, RESOURCE_EXPIRED
403	Invalid credentials	MISSING_API_KEY_OR_ACCOUNT INVALID_CREDENTIALS

Stores and products

Feed documentation

Setting your feed up is not a difficult process.
Make sure there is a feed available with products and categories. Categories are optional.
The feed can be in xml or json format and should look like this:


<?xml version="1.0" encoding="UTF-8"?>
<data>
    <products>
        <product>
            <name>Product X</name>
            <description>Product X description</description>
            <price>19.99</price>
            <currency>EUR</currency>
            <availability>in stock</availability>
            <image>http://www.yourstore.com/productx.jpg</image>
            <url>http://www.yourstore.com/productx</url>
            <inventory>24</inventory>
            <condition>new</condition>
            <brand>Brand Y</brand>
            <product_id>PR00019X</product_id>
            <category_ids>["1234","1235"]</category_ids>
            <parent_id>ABC123</parent_id>
        </product>
        ...
    </products>
    <categories>
        <category>
            <name>Category X</name>
            <description>Category X description</description>
            <url>http://www.yourstore.com/categoryx</url>
            <category_id>1234</category_id>
        </category>
        ...
    </categories>
</data>

Products property description:

property	description
name	Name of the product
description	Description of the product
price	Price in decimals (no thousand separator, dot for decimal separator). Example: 1345.50
currency	Currency (EUR/USD/GBP)
availability	in stock, out of stock or available for order
image	URL of the main image of the product
url	URL of the product
inventory	Amount of products in stock
condition	new or used
brand	Brand of the product
product_id	SKU or EAN you communicate with your customers. This needs to be unique.
category_ids	Categories that have this product. JSON list of category ids.
parent_id	Products with the same parent id will be grouped as variants in your feed

Category property description:

property	description
name	Name of the category
description	Description of the category
url	Url of the category
category_id	SKU or your internal category id or reference. Required, unique.

Feed documentation

Looking for the old version of the feed?

It's here!

With a feed you can easily keep your product data in sync.
The feed should be formatted in either XML RSS 2.0 or ATOM 1.0 format. The Squeezely feed also supports Google Merchant Center Product Data feeds.

Supported properties

The following fields are supported in the feed.

property	description
id	The unique product ID (SKU or EAN)	Mandatory
title	Name of the product	Mandatory
link	URL of the product	Mandatory
description	Description of the product
price	The price and currency of the product (EUR/USD/GBP). Price in decimals (no thousand separator, dot for decimal separator). Example: 1345.50 EUR
availability	in stock, out of stock, available for order, preorder
image_link	URL of the main image of the product
image_links	Supply up to 20 images for your product. (Overwrites image_link field). List of <image_link> elements containing an url.
condition	Condition of the product, new, used, refurbished.
Inventory	Amount of products in stock
brand	Brand of the product
parent_id	Products with the same parent id will be grouped as variants in your catalog.
category_ids	Categories that have this product. List of <category_id> elements containing an id.
google_product_category	Include either the full path of the Google category or the numerical category ID. Please refer to the Google Product Taxonomy documentation.

Note on google_product_category

The Google Product Taxonomy Supports either numerical category identifiers, or a string containing the entire path of the category. Our platform needs to convert these to a consistent single format. For this we use the numerical category identifier.
It is important when using the full textual category paths to select the correct category path naming language. This way our platform can convert those to numerical ones. Currently Google supports the following unique languages:

Categories and Languages

A feed contains products of 1 language.
You can create your own categories, or you can use the google categories.

Supported properties for categories

property	description
title	Title of the category
description	Description of the category
url	Url of the category
category_id	SKU or your internal category id or reference. Required, unique.

Using Google categories

Language	Identifier	Google category list
Deutsch	de-DE	Open list
English (United Kingdom)	en-GB	Open list
English	en-US	Open list
español (Latinoamérica)	es-ES	Open list
français	fr-FR	Open list
Nederlands‎	nl-NL	Open list
norsk	no-NO	Open list
polski	pl-PL	Open list
Türkçe	tr-TR	Open list
日本語	ja-JP	Open list

More information on Google feeds

Please refer to the Google Merchant Center Product data specification documentation for more details about the specific feed specifications, and example files.