Introduction

Welcome to Betaout API documentation!



This document covers how to use the Betaout API that allows you to retrieve and work with core aspects of our software. The Betaout API provides developers to work with three entities - users, custom events and e-commerce activity. You can switch the programming language on the top left.

API Endpoint - The base URI for the API key is, http://PROJECTID.betaout.in/v1
API summary - The API can be summarised under the following resources.

API area Resource area Description
Identify http://PROJECTID.betaout.in/v1/user/identify You can send signed-in users to identify them.
Add http://PROJECTID.betaout.in/v1/user/add append in the value of the property.
Increment http://PROJECTID.betaout.in/v1/user/increment Increment in the value of the property.
Update http://PROJECTID.betaout.in/v1/user/update 'Update' will replace old values (if present) of these properties.
Event http://PROJECTID.betaout.in/v1/user/event Use events to submit user activity to Betaout.
Customer activity http://PROJECTID.betaout.in/v1/user/customer_activity submit the commonly used e-commerce user activities.

Authentication

Every request is made over HTTPS and it should be accompanied by API key and project ID. From your Betaout account you can easily obtain your API key, API secret and project ID. Your API key is available on Ideas & Docs page of Betaout.

Please include javascript snippet in between your <head> </head> tags on all pages of your website.

<script type="text/javascript">
var _bOut = _bOut || [];var 

_bOutAKEY = "--YOUR API KEY--", 
_bOutPID = "--YOUR PROJECT ID --", 

_bOutCW = true, _bOutST = true;var d = document, f =d.getElementsByTagName("script")[0], _sc =d.createElement("script");_sc.type = "text/javascript";_sc.async = true;_sc.src = "//d22vyp49cxb9py.cloudfront.net/jal-v1.min.js";f.parentNode.insertBefore(_sc, f);
</script>
                                        

User

The users resource is the foremost way of interacting with Betaout. You can create and update your users, and add custom attributes while describing them. You can also view your users individually or as a list and can query using tags and segments.

User Identification

You can send name and email address of your signed-in users to identify them. Email address is used to identify different users.
_bOut.push(["identify",{
    "email": "bill@gates.com",
    "name": "Bill Gates"
  }]);
                                            

User Property Add

By this you can add multiple properties with the user. Like first name, last name, gender, age etc.
_bOut.push(["add","bill@gates.com", {
     "propertyName": "propertyValue",
     "property2Name": "property2Value",  
 }]);
                                            

User Property Update

You can send custom properties for users. 'Update' will replace old values (if present) of these properties

Note: If you want to create any date specific property, then property name should end with '_date' for e.g. 'birth_date', 'Signup_date', 'Subscribe_date' etc. You have to send dates in Unix timestamp format.
_bOut.push(["update","bill@gates.com", {
     "plan_type": "gold plan",
     "propertyName": "propertyValue",
     "property2Name": "property2Value",
     "lastseen_date": "4364763483"
  }]);
                                            

User Property Increment

If you want to increase any numeric property you have to use this increment API. Like age, total revenue, etc. This increment property will not work on date and text properties.
_bOut.push(["increment","bill@gates.com", {
      "revenue": 1000,
      "totalPrice": 1230.50,
   }]);
                                            

Ecommerce Methods

Customer Activity

Field Type Field Type Description Example
email varchar required abc@gmail.com
actionName varchar required 'viewed','purchased','add_to_cart','removed_from_cart' purchased
products multivalue array required see below 1.1
cartinfo array required when action_name purchased,add_ to_cart,'removed_from_cart' see below 1.2

Product

Field Type Field Type Description Example
productId varchar required
sku varchar optional
productTitle multivalue array required
price double required
specialPrice double optional
status enum optional ('enabled','disabled') by default it's enabled
stockAvailability enum optional (1,0) 1 for Availability by default it's enabled
pageURL varchar optional
pictureURL varchar optional
currency varchar required
qty number optional number of item added
category varchar optional comma seperated string 'ct1','ct2'

OderInfo

Field Type Field Type Description Example
orderId varchar required when action name purchased
shoppingCartNo varchar optional
subtotalPrice double required
totalShippingPrice double optional
totalTaxes double optional
totalPrice double optional after adding with shipping and tax
promocode varchar optional comma seperated string 'p1','p2'
couponcode varchar optional comma seperated string 'c1','c2'
abandonedCheckoutUrl varchar optional
financialStatus enum optional 'pending','authorized','partial_paid','paid','partialy_refund','refunded','voided' "paid"

Purchased

The Purchase API helps to capture the details of purchase - product/s and order info. The product details consist of product info and quantity.
_bOut.push(["customerActivity", "bill@gates.com", "purchased", {
                    "products": [{
                            "productId": "Samsung2322",
                            "sku": "Samsung2322",
                            "productTitle": "Samsung2322",
                            "price": 12333,
                            "specialPrice": 12,
                            "status": "enable",
                            "stockAvailability": 1,
                            "brandName": "XXX",
                            "totalProductPrice": 100,
                            "promocode": "xyz123",
                            "discountPrice": 20,
                            "pageURL": "xxx",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "2": {
                                    "n": "asd",
                                    "p": "0"
                                }, "3": {
                                    "n": "asd",
                                    "p": "2"
                                }
                            },
                            "qty": 1
                        }, {
                            "productId": "Samsung2",
                            "sku": "Samsung2",
                            "productTitle": "Samsung2",
                            "price": 123,
                            "specialPrice": 23,
                            "status": "disable",
                            "stockAvailability": 1,
                            "brandName": "xxx",
                            "pageURL": "xxx2",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "4": {
                                    "n": "asd_1",
                                    "p": "0"
                                }, "5": {
                                    "n": "asd_2",
                                    "p": "4"
                                }
                            }, "qty": 1
                        }],
                    "orderInfo": {
                        "orderId": "XSYER",
                        "currency": "INR",
                        "shoppingCartNo": "68778783ad298f13bafcddeea",
                        "subtotalPrice": 4352,
                        "totalShipping": 0.06,
                        "totalTaxes": 0.06,
                        "totalDiscount": 0.06,
                        "totalPrice": 12,
                        "promocode": "XXX",
                        "couponcode": "XXX",
                        "financialStatus": "paid",
                        "discountPercentage": 0.50,
                        "appType": "web",
                        "paymentMethod": "Debit"
                    }
            }]);
                                            

Viewed

This API helps you to capture event of product view by user. You can pass event of viewed details of product with this API.
_bOut.push(["customerActivity", "bill@gates.com", "viewed", {
                    "products": [{
                            "productId": "Samsung2322",
                            "sku": "Samsung2322",
                            "productTitle": "Samsung2322",
                            "price": 12333,
                            "specialPrice": 12,
                            "status": "enable",
                            "stockAvailability": 1,
                            "brandName": "XXX",
                            "pageURL": "xxx",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "2": {
                                    "n": "asd",
                                    "p": "0"
                                }, "3": {
                                    "n": "asd",
                                    "p": "2"
                                }
                            },
                            "qty": 1
                        }, {
                            "productId": "Samsung2",
                            "sku": "Samsung2",
                            "productTitle": "Samsung2",
                            "price": 123,
                            "specialPrice": 23,
                            "status": "disable",
                            "stockAvailability": 1,
                            "brandName": "xxx",
                            "pageURL": "xxx2",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "4": {
                                    "n": "asd_1",
                                    "p": "0"
                                }, "5": {
                                    "n": "asd_2",
                                    "p": "4"
                                }
                            }, "qty": 1
                        }]
                }]);
                                            

Add To Cart

This API is for event when a user adds any product to cart.
_bOut.push(["customerActivity", "bill@gates.com", "add_to_cart", {
                    "products": [{
                            "productId": "Samsung2322",
                            "sku": "Samsung2322",
                            "productTitle": "Samsung2322",
                            "price": 12333,
                            "specialPrice": 12,
                            "status": "enable",
                            "stockAvailability": 1,
                            "brandName": "XXX",
                            "pageURL": "xxx",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "2": {
                                    "n": "asd",
                                    "p": "0"
                                }, "3": {
                                    "n": "asd",
                                    "p": "2"
                                }
                            },
                            "qty": 1
                        }],
                    "orderInfo": {
                    "totalDiscount": "20",
                    "currency": "INR",
                    "discountPercentage": 20,
                    "appType": "web",
                    "subtotalPrice": 100,                       
                    "abandonedCheckoutUrl": "https://www.bt.com/orders/18/6?recovered=1"                       
                        }
                    }]);
                                            

Removed From Cart

A customer, at times might want to remove some or all of the items from their shopping cart. This request sets the product specified to be removed from the cart.
_bOut.push(["customerActivity", 'bill@gates.com', 'removed_from_cart', {
                    "products": [{
                            "productId": "Samsung2322",
                            "sku": "Samsung2322",
                            "productTitle": "Samsung2322",
                            "price": 12333,
                            "specialPrice": 12,
                            "status": "enable",
                            "stockAvailability": 1,
                            "brandName": "XXX",
                            "pageURL": "xxx",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "2": {
                                    "n": "asd",
                                    "p": "0"
                                }, "3": {
                                    "n": "asd",
                                    "p": "2"
                                }
                            },
                            "qty": "1"
                        }, {
                            "productId": "Samsung2",
                            "sku": "Samsung2",
                            "productTitle": "Samsung2",
                            "price": 123,
                            "specialPrice": 23,
                            "status": "disable",
                            "stockAvailability": 1,
                            "brandName": "xxx",
                            "pageURL": "xxx2",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "4": {
                                    "n": "asd_1",
                                    "p": "0"
                                }, "5": {
                                    "n": "asd_2",
                                    "p": "4"
                                }
                            }, "qty": 1
                        }],
                    "orderInfo": {
                    "totalDiscount": "20",
                    "currency": "INR",
                    "discountPercentage": 20,
                    "appType": "web",
                    "subtotalPrice": 100,                       
                    "abandonedCheckoutUrl": "https://www.bt.com/orders/18/6?recovered=1"                    
                        }
                    }]);
                                            

Removed From Cart

A customer, at times might want to remove some or all of the items from their shopping cart. This request sets the product specified to be removed from the cart.
_bOut.push(["customerActivity", 'bill@gates.com', 'update_cart', {
                    "products": [{
                            "productId": "Samsung2322",
                            "sku": "Samsung2322",
                            "productTitle": "Samsung2322",
                            "price": 12333,
                            "specialPrice": 12,
                            "status": "enable",
                            "stockAvailability": 1,
                            "brandName": "XXX",
                            "pageURL": "xxx",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "2": {
                                    "n": "asd",
                                    "p": "0"
                                }, "3": {
                                    "n": "asd",
                                    "p": "2"
                                }
                            },
                            "qty": 3
                        }, {
                            "productId": "Samsung2",
                            "sku": "Samsung2",
                            "productTitle": "Samsung2",
                            "price": 123,
                            "specialPrice": 23,
                            "status": "disable",
                            "stockAvailability": 1,
                            "brandName": "xxx",
                            "pageURL": "xxx2",
                            "pictureURL": "",
                            "currency": "INR",
                            "category": {
                                "4": {
                                    "n": "asd_1",
                                    "p": "0"
                                }, "5": {
                                    "n": "asd_2",
                                    "p": "4"
                                }
                            }, "qty": 2
                        }],
                    "orderInfo": {
                    "totalDiscount": 20,
                    "currency": "INR",
                    "discountPercentage": 20,
                    "appType": "web",
                    "subtotalPrice": 100,                       
                    "abandonedCheckoutUrl": "https://www.bt.com/orders/18/6?recovered=1"                    
                        }
                    }]);