VBOUT - Ecommerce Tracking Documentation Version 1.0 (BETA)

Introduction

This guide describes how to send ecommerce (cart/order) data to your VBOUT account.

Getting Started #back to top

Overview

There are two types of ecommerce data you can send:
  1. Cart Data
    Represents the cart and its product items
  2. Order Data
    Represents the successful order/purchase

Enable Ecommerce Tracking

To enable VBOUT ecommerce tracking plugin, go to your VBOUT Account's settings page, Website Tracking Code option, and find domain settings. Activate the e-commerce tracking under the "Domain Settings". Once the settings is enabled, you can start using the ecommerce code below to send cart and order data to your VBOUT account.

Implementation

You can implement ecommerce tracking while the user is adding an item on the shopping cart or once the user has successfully completed the checkout process.

_vbset.push(["COMMAND", {
	// data to be passed to VBOUT's Ecommerce Tracking account
}]);

Sync Cart Data #back to top

Cart Item Object

Cart Item object contains the following values:
Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
productid text Yes The product ID. The unique ID of the item (e.g. 123)
name text Yes The item name (e.g. Navy Sweatshirt)
price currency Yes The individual, unit, price for each item (e.g. 11.99)
discountprice currency - The individual, unit, discount price for each item (e.g. 10.99)
quantity integer Yes The number of units purchased in the transaction (e.g. 2)
sku text - Specifies the SKU or item code (e.g. SKU12)
categoryid text - The category ID to which the item belongs (e.g. 19)
category text - The category name to which the item belongs (e.g. Clothing)
link text - The link url of the product item (e.g. https://domain.com/clothing/product/123)
image text - The image url of the product item (e.g. https://domain.com/images/product-123.jpg)
description text - The item description (e.g. This Navy Sweatshirt fits all sizes.)

Cart Details Object

Cart Details object contains the following values:
Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
storename text - The name of the store from which this transaction occurred (e.g. Acme Clothing)
abandonurl text - The cart's abandon url link when the user dose not proceed with the purchase (e.g. http://domain.com/cart.php?c=abandonurl)
customer text - Customer email address (e.g. john@smith.com)

Adding Cart Item

Once the plugin is enabled, it creates a transparent shopping cart object. You can now add items to your shopping cart object.

All products should be sent together each time in order to update your cart in your VBOUT's account.
_vbset.push(["store.cart.item", {
	"cartid": "123456", //Cart ID [Required] 
	"productid": "22",	//Product ID [Required] 
	"name": "Fluffy Pink's Bunnies", //Product name [Required]
	"price": "11.99", //Unit price [Required] 
	"discountprice": "10.99", //Unit discount price
	"quantity": "1", //Quantity [Required]
	"sku": "DD23444", //SKU/code. 
	"categoryid": "cat-123", //Category or variation ID. 
	"category": "Party Toys", //Category or variation name. 
	"link": "http://domain.com/product.php?id=123456",
	"image": "http://domain.com/uploads/products/123456.jpg"
}]);

The above code should be repeated for each product in your cart. Check below example:

_vbset.push(["store.cart.item", {
	"cartid": "123456",
	"productid": "22",
	"name": "Fluffy Pink's Bunnies",
	"price": "11.99",
	"quantity": "1"
}]);
_vbset.push(["store.cart.item", {
	"cartid": "123456",
	"productid": "23",
	"name": "Fluffy Bunny Backpack SD00055",
	"price": "15.99",
	"quantity": "1"
}]);
_vbset.push(["store.cart.item", {
	"cartid": "123456",
	"productid": "25",
	"name": "Pink fluffy bunny slippers",
	"price": "9.99",
	"quantity": "1"
}]);
_vbset.push(["store.cart.item", {
	"cartid": "123456",
	"productid": "27",
	"name": "Fluffy Pink Rabbit Ears",
	"price": "5.99",
	"quantity": "1"
}]);

Adding Cart Details

"customer" should be sent with cart's details to link this cart to this customer in your VBOUT's account
_vbset.push(["store.cart.data", {
	"cartid": "123456", //Cart ID [Required] 
	"customer": "john@smith.com", // customer's email address
	"storename": "My Store", // Store name
	"abandonurl": "http://domain.com/cart.php?c=sampleabandonurl" //Abandon cart link.
}]);

Sending Cart Details

Send the data once you have configured all your ecommerce data in the shopping cart. This command will sync cart data to your VBOUT account.

_vbset.push(["store.cart.send"]);

Clearing Cart Details

You can manually clear the shopping cart data.

_vbset.push(["store.cart.clear"]);

Sync Order Data #back to top

Order Details Object

Order Data contains the following values:
Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
orderid text Yes The order ID. The unique ID of the successful order/purchase (e.g. 12345)
orderdate timestamp - The order date. Date should be in Unix timestamp format (e.g. 1531537877))
paymentmethod text Yes The payment method used (e.g. Mastercard)
shippingmethod text - The shipping method used (e.g. Fedex)
shippingcost float - The shipping cost (e.g. 10.00)
storename text - The name of the store from which this transaction occurred (e.g. Acme Clothing)
grandtotal float Yes The final amount after tax cost, discounts, and other fees are added up. (e.g. 105.99)
subtotal float - The total amount without the tax, discounts, and other fees. (e.g. 45.44)
promocode text - The promo name/code (e.g. the-offer)
promovalue float - The promo cost (e.g. 5.00)
discountcode text - The discount name/code (e.g. 10off)
discountvalue float - The discount value (e.g. 10.00)
taxname text - The tax name/code (e.g. Value Added Tax)
taxcost float - The tax cost (e.g. 5.00)
otherfeename text - The other fee name/code (e.g. Handling Fee)
otherfeecost float - The other fee cost (e.g. 5.00)
currency text - The currency used to purchase. (e.g. USD )
status text - The status of the purchase. (e.g. In Progress)
notes text - The notes of the order. (e.g. A note for order)
customerinfo object Yes The customer's information.
billinginfo object - The order's billing information.
shippinginfo object - The order's shipping information.

Order Customer Object

Order Customer Object contains the following values:
Key Value Type Required Description
firstname text - Customer first name (e.g. John)
lastname text - Customer last name (e.g. Smith)
email text Yes Customer email address (e.g. john@smith.com)
phone text - Customer phone number (e.g. 1-800-123-1234)
company text - Customer company name (e.g. MyCompany Ltd.)

Order Billing Object

Order Billing Object contains the following values:
Key Value Type Required Description
firstname text - Billing first name (e.g. John)
lastname text - Billing last name (e.g. Smith)
email text - Billing email address (e.g. john@smith.com)
phone text - Billing phone number (e.g. 1-800-123-1234)
company text - Billing company name (e.g. MyCompany Ltd.)
address text - Billing address (e.g. 1601 Willow Road)
address2 text - Billing address (Line 2) (e.g. Menlo Park)
city text - Billing city (e.g. New York)
statename text - Billing State name (e.g. California)
statecode text - Billing State code (e.g. CA)
countryname text - Billing Country name (e.g. United States)
countrycode text - Billing Country code (e.g. US)
zipcode text - Billing postal code (e.g. 94205)

Order Shipping Object

Order Shipping Object contains the following values:
Key Value Type Required Description
firstname text - Shipping first name (e.g. John)
lastname text - Shipping last name (e.g. Smith)
email text - Shipping email address (e.g. john@smith.com)
phone text - Shipping phone number (e.g. 1-800-123-1234)
company text - Shipping company name (e.g. MyCompany Ltd.)
address text - Shipping address (e.g. 1601 Willow Road)
address2 text - Shipping address (Line 2) (e.g. Menlo Park)
city text - Shipping city (e.g. New York)
statename text - Shipping State name (e.g. California)
statecode text - Shipping State code (e.g. CA)
countryname text - Shipping Country name (e.g. United States)
countrycode text - Shipping Country code (e.g. US)
zipcode text - Shipping postal code (e.g. 94205)

Adding Order Details

When a user completes an order, you can use below command to add order details to your transparent order object.

_vbset.push(["store.order.data", {
	"cartid": "123456", //Cart ID [Required] 
	"orderid": "12", //Order ID [Required] 
	"paymentmethod": "Mastercard",	//Payment method [Required] 
	"grandtotal": 100.00, //Grand total amount [Required] 
	"orderdate": "1531454869", //Order Date in timestamp. 
	"shippingmethod": "Fedex", //Shipping method
	"shippingcost": 55.55,	//Shipping cost 
	"subtotal": 70.00, //Sub-total amount. 
	"discountcode": "10off",	//Discount name/code
	"discountvalue": 10.00,	//Discount  amount 
	"promocode": "5off",	//Promo code
	"promovalue": 5.00,	//Promo amount 
	"taxname": "", //Tax name/code
	"taxcost": 0.00, //Tax amount
	"otherfeename": "handling fee",	//Other fees name
	"otherfeecost": 3.00,	//Other fees amount
	"currency": "USD",	//Currency. 
	"status": "In Progress",	// Order Status. 
	"notes": "A note for order",	// Order Notes. 
	"storename": "My Store",
	"customerinfo": {
		"firstname": "John",	//Customer first name. 
		"lastname": "Smith",	//Customer last name 
		"email": "john@smith.com",	//Customer email address [Required] 
		"phone": "1-800-123-1234",	//Customer phone number. 
		"company": "MyCompany Ltd.",	//Customer company name. 
	},
	"billinginfo": {
		"firstname": "John", //Billing first name
		"lastname": "Smith", //Billing last name
		"email": "john@smith.com",	//Billing email address
		"phone": "1-800-123-1234",	//Billing phone number
		"company": "MyCompany Ltd.",	//Billing company name
		"address": "1601 Willow Road",	//Billing address
		"address2": "Menlo Park",	//Billing address (Line 2) 
		"city": "New York", //Billing city. 
		"statename": "California",	//Billing State name
		"statecode": "CA",	//Billing State code
		"countryname": "United States",	//Billing Country name
		"countrycode": "US",	//Billing Country code
		"zipcode": "94205", //Billing postal code
	},
	"shippinginfo": {
		"firstname": "John", //Shipping first name
		"lastname": "Smith", //Shipping last name
		"email": "john@smith.com",	//Shipping email address
		"phone": "1-800-123-1234",	//Shipping phone number
		"company": "MyCompany Ltd.",	//Shipping company name
		"address": "1601 Willow Road",	//Shipping address
		"address2": "Menlo Park",	//Shipping address (Line 2)
		"city": "New York", //Shipping city
		"statename": "California",	// Shipping State name
		"statecode": "CA",	// Shipping State code
		"countryname": "United States",	// Shipping Country name
		"countrycode": "US",	// Shipping Country code
		"zipcode": "94205", // Shipping postal code
	}
}]);

Sending Order Details

Send the data once you have configured all order data. This command will sync order data to your VBOUT account.

_vbset.push(["store.order.send"]);

Clearing Order Details

Manually clear the order data.

_vbset.push(["store.order.clear"]);

Sync ShoppingCart Data #back to top

Product Search Object

Search Data contains the following values:
Key Value Type Required Description
query text Yes Search Query (e.g. iPhone)
customer text - Customer email address (e.g. john@smith.com)

Product View Object

Product Data contains the following values:
Key Value Type Required Description
customer text - Customer email address (e.g. john@smith.com)
productid text Yes The product ID. The unique ID of the product (e.g. 123)
name text Yes The product name (e.g. Navy Sweatshirt)
price currency Yes The individual, unit, price for the product (e.g. 11.99)
discountprice currency - The individual, unit, discount price for the product (e.g. 10.99)
sku text - Specifies the SKU or product code (e.g. SKU12)
categoryid text - The category ID to which the product belongs (e.g. 19)
category text - The category name to which the product belongs (e.g. Clothing)
link text - The link url of the product item (e.g. https://domain.com/clothing/product/123)
image text - The image url of the product item (e.g. https://domain.com/images/product-123.jpg)
description text - The product description (e.g. This Navy Sweatshirt fits all sizes.)

Category View Object

Category Data contains the following values:
Key Value Type Required Description
customer text - Customer email address (e.g. john@smith.com)
categoryid text Yes The category ID. The unique ID of the category (e.g. cat-123)
name text Yes The category name (e.g. Clothing)
link text - The link url of the category (e.g. https://domain.com/clothing/cat-123)
image text - The image url of the category (e.g. https://domain.com/images/category-cat-123.jpg)
description text - The category description (e.g. Clothing fits all sizes.)

Adding Search Details

When a user search for a product, you can use below command to send his search term details to your VBOUT's account.

"customer" should be sent with search's details to link this search to this customer in your VBOUT's account
_vbset.push(["store.product.search", {
	"query": "iPhone", // Search query [Required] 
	"customer": "john@smith.com" // customer's email address
}]);

Adding Product View

When a user visit/view product page, you can use below command to send his visit details to your VBOUT's account.

"customer" should be sent with product's details to link this visit/view to this customer in your VBOUT's account
_vbset.push(["store.product.view", {
	"customer": "john@smith.com", // customer's email address
	"productid": "22",	//Product ID [Required] 
	"name": "Fluffy Pink's Bunnies", //Product name [Required]
	"price": "11.99", //Unit price [Required] 
	"discountprice": "10.99", //Unit discount price
	"sku": "DD23444", //SKU/code. 
	"categoryid": "cat-123", //Category or variation ID. 
	"category": "Party Toys", //Category or variation name. 
	"link": "http://domain.com/product.php?id=123456",
	"image": "http://domain.com/uploads/products/123456.jpg"
}]);

Adding Category View

When a user visit/view category page, you can use below command to send his visit details to your VBOUT's account.

"customer" should be sent with category's details to link this visit/view to this customer in your VBOUT's account
_vbset.push(["store.category.view", {
	"customer": "john@smith.com", // customer's email address
	"categoryid": "cat-123", //Category ID [Required] 
	"name": "Party Toys", //Category name [Required] 
	"link": "http://domain.com/category.php?id=cat-123",
	"image": "http://domain.com/uploads/category/cat-123.jpg"
}]);
open navigation