Tracking E-Commerce Events in CustomerLabs

E-commerce events actions that users perform in an e-commerce website / app.

E-Commerce Events

The following events are standard e-commerce events that are tracked in CustomerLabs,

• Product viewed
• Added to cart
• Checkout made
• AddPaymentInfo
• Purchased

Danger

If events are configured via Google Tag Manager (GTM), ensure that the event name triggered to CustomerLabs and the GTM trigger event name does not match. Otherwise, it will trigger an infinite loop of events.

Example, for dataLayer.push ({'event': 'purchase', 'ecommerce': {...}})

_cl.trackClick('purchase', properties) should NOT be set up.

Instead, the event name should be modfied to something else like _cl.trackClick('cl_browser_purchase', properties)

Tip

As you can notice, the event names are slightly modified to avoid the earlier confusion.

However, when these events are sent to other platforms that have native integration with CustomerLabs, they are transformed to the standard e-commerce events of the respective platform.

Properties Object

Mandatory Parameters

The following paramters are mandatory for all the e-commerce events. These should be included either in customProperties or productProperties object.

Parameter	Property	Type	Description
value	customProperties	number	The value of the event.
currency	customProperties	string	The currency of the event.
product_name	productProperties	string	The name of the product.
product_id	productProperties	string	The ID of the product.
product_price	productProperties	number	The price of the product.
product_quantity	productProperties	number	The quantity of the product.

Optional Parameters

Parameter	Property	Type	Description
product_brand	productProperties	string	The brand of the product.
product_category	productProperties	string	The category of the product.
product_variant	productProperties	string	The variant of the product.
product_image_url	productProperties	string	The URL of the product image.
product_variant_id	productProperties	string	The variant ID of the product.
product_sku	productProperties	string	The SKU of the product.

Product Viewed

This event is tracked when user visits a product page. This event is transformed to ViewContent event for Meta Pixel.

Syntax

Javascript

var properties = {
    "customProperties": {
        // Custom Properties
    },
    "productProperties": [
        { // productProperies}
    ]
}
_cl.pageview("Product viewed", properties)

Example

Javascript

var eventName = "Product viewed";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 100
    }
  },
  "productProperties": [
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        }
    ]
};

_cl.pageview(eventName, properties);

Added to Cart / Removed from cart

Added to cart is triggered when user adds a product to the cart and Removed from cart is triggered when user removes a product from the cart.

Syntax

Javascript

var properties = {
    "customProperties": {
        // Custom Properties
    },
    "productProperties": [
        { // productProperies}
    ]
}
_cl.trackClick("Added to cart", properties)

Example

Javascript

var eventName = "Added to Cart";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 100
    }
  },
  "productProperties": [
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        }
    ]
};

_cl.trackClick(eventName, properties);

Removed from cart

Removed from cart is opposite of Added to cart event. The syntax and properties are same as Added to cart event.

Checkout made

This event is triggered when user proceeds to checkout page.

Syntax

Javascript

var properties = {
    "customProperties": {
        // Custom Properties
    },
    "productProperties": [
        { // productProperies 1},
        { // productProperies 2}
    ]
}
_cl.trackClick("Checkout made", properties)

Example

Javascript

var eventName = "Checkout made";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 149
    }
  },
  "productProperties": [
        // sample product 1
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        },
        // sample product 2
        {
            "product_id": {
                "t": "string",
                "v": "PRD-2-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 2"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 49
            }
        }
    ]
};

_cl.trackClick(eventName, properties);

AddPaymentInfo

This event is triggered when user adds payment and shipping information to the cart. This event is crucial as it will capture the user_traits.

Syntax

Javascript

var properties = {
    "customProperties": {
        // Custom Properties,
        // user_traits,
        // external ids,
        // identify_by
    },
    "productProperties": [
        { // productProperies 1},
        { // productProperies 2}
    ]
}
_cl.trackClick("AddPaymentInfo", properties)

Example

Example 1 - Without user_traits and external_ids

In this example, we are triggering the AddPaymentInfo event without user_traits and external_ids. This is a simple example to show how to trigger the AddPaymentInfo event.

Javascript

var eventName = "AddPaymentInfo";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 149
    }
  },
  "productProperties": [
        // sample product 1
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        },
        // sample product 2
        {
            "product_id": {
                "t": "string",
                "v": "PRD-2-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 2"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 49
            }
        }
    ]
};

_cl.trackClick(eventName, properties);

Example 2 - With user_traits and external_ids

In this exmaple, we will see how to trigger the AddPaymentInfo event with user_traits and external_ids. Since there are user_traits and external_ids in this event, we will also trigger the identify event.

Javascript

var eventName = "AddPaymentInfo";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 149
    },
    "user_traits": {
        "email": {
            "t": "string",
            "v": "johndoe@example.com"
        },
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "phone": {
            "t": "string",
            "v": "1234567890"
        },
        "address1": {
            "t": "string",
            "v": "1234, Sunset Boulevard"
        },
        "address2": {
            "t": "string",
            "v": "Apt 123"
        },
        "city": {
            "t": "string",
            "v": "Los Angeles"
        },
        "state": {
            "t": "string",
            "v": "CA"
        },
        "zip": {
            "t": "string",
            "v": "90001"
        },
        "country": {
            "t": "string",
            "v": "USA"
        }
    },
    "external_ids": {
        "identify_by_email": {
            "t": "string",
            "v": "johndoe@example.com"
        },
        "identify_by_phone": {
            "t": "string",
            "v": "1234567890"
        }
    },
    "identify_by_email": {
        "t": "string",
        "v": "johndoe@example.com",
        "ib": true
    }
  },
  "productProperties": [
        // sample product 1
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        },
        // sample product 2
        {
            "product_id": {
                "t": "string",
                "v": "PRD-2-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 2"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 49
            }
        }
    ]
};

// event trigger to CustomerLabs
_cl.trackClick(eventName, properties);

var email = properties.customProperties.identify_by_email.v;

// identify user only when email exists
if (email) {
  _cl.identify(properties);
}

Purchased

Purchased event is triggered when a user successfully purchases a product. This is the pinnacle of e-commerce journey, as it captures the complete purchase journey of a user. This event is crucial as it will capture the user_traits and external_ids.

Additional Required Parameters

In addition to all the commonly required parameters, Purchased event has the following additional required parameters,

• transaction_id
• order_number / order_id

These 2 parameters should be added to customProperties.

Syntax

Javascript

var properties = {
    "customProperties": {
        // Custom Properties,
        // user_traits,
        // external ids,
        // identify_by
    },
    "productProperties": [
        { // productProperies 1},
        { // productProperies 2}
    ]
}
_cl.trackClick("Purchased", properties)

Example

Javascript

var eventName = "Purchased";

var properties = {
  "customProperties": {
    "currency": {
      "t": "string",
      "v": "USD"
    },
    "value": {
      "t": "number",
      "v": 149
    },
    "transaction_id": {
      "t": "string",
      "v": "cl-pay-1234567890"
    },
    "order_number": {
      "t": "string",
      "v": "cl-order-1234567890"
    },
    "user_traits": {
        "email": {
            "t": "string",
            "v": "johndoe@example.com"
        },
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "phone": {
            "t": "string",
            "v": "1234567890"
        },
        "address1": {
            "t": "string",
            "v": "1234, Sunset Boulevard"
        },
        "address2": {
            "t": "string",
            "v": "Apt 123"
        },
        "city": {
            "t": "string",
            "v": "Los Angeles"
        },
        "state": {
            "t": "string",
            "v": "CA"
        },
        "zip": {
            "t": "string",
            "v": "90001"
        },
        "country": {
            "t": "string",
            "v": "USA"
        }
    },
    "external_ids": {
        "identify_by_email": {
            "t": "string",
            "v": "johndoe@example.com"
        },
        "identify_by_phone": {
            "t": "string",
            "v": "1234567890"
        }
    },
    "identify_by_email": {
        "t": "string",
        "v": "johndoe@example.com",
        "ib": true
    }
  },
  "productProperties": [
        // sample product 1
        {
            "product_id": {
                "t": "string",
                "v": "PRD-1-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 1"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 100
            }
        },
        // sample product 2
        {
            "product_id": {
                "t": "string",
                "v": "PRD-2-ID"
            },
            "product_name": {
                "t": "string",
                "v": "Sample Product 2"
            },
            "product_quantity": {
                "t": "number",
                "v": 1
            },
            "product_price": {
                "t": "number",
                "v": 49
            }
        }
    ]
};

// event trigger to CustomerLabs
_cl.trackClick(eventName, properties);

var email = properties.customProperties.identify_by_email.v;

// identify user only when email exists
if (email) {
  _cl.identify(properties);
}

Note

It is best practice that Purchased event should contain the user_traits and external_ids and identify is triggered. This ensures 100% accuracy in user identification.

Additional E-commerce Events

These are additional e-commerce events that can be tracked in CustomerLabs.

• Category viewed - Tracked when user visits a category / collection page.
• Cart viewed - Tracked when user visits a cart page.
• AddShippingInfo - This can be tracked along with AddPaymentInfo event or as a standalone event when user enters their shipping information.
• Added to wishlist - Tracked when user adds a product to their wishlist.
• Removed from wishlist - Tracked when user removes a product from their wishlist.

Custom E-Commerce Events

Apart from the standard e-commerce events and above mentioned events, you can track your own custom e-commerce events based on your business requirements.

For example, if your want to track a event when a user clicks on the “Buy Now” button, you can track a custom event Buy Now Clicked.