ServerSide Integration

Overview

For a server-side integration of events the following steps are required:

• obtaining an API key for the account (used to authorize requests)
• providing a product feed
• implementing tracking script on the front-end.

General tips:

• please make sure data types and structure is valid
• parameters and field names are case-sensitive. orderId is different from orderid

Our standard events API facilitates the transmission of confirmation events (orders) to the VTmarketing platform.

Endpoint	https://api.vtcdn.net/v1/event/
Request Type	POST
Headers	Authorization: api_key
Headers	Content-Type: application/json

Authentication

Each account is assigned a unique API key which serves as an authentication token for accessing our API. Upon registration, each account API key needs to be securely stored on your end. This key is essential for authenticating API requests and ensuring secure communication between your system and our platform. Please ensure that you keep this API key confidential and do not share it with unauthorized parties.

Payload

With the following JSON encoded payload.

It has 2 mandatory parameters: user and event. Each of them is described below

“user”	{"email": "[email protected]", "tel": "0775123123"}
“event”:	{ "confirmation": { "generic": { "orderId": "unique_order_id", "total": 400.33, "status":"order_status", "coupons":["coupon1", "coupon2"], "phone":"phone number", "currency": "RON", "total_shipping": 22.00 }, "items":[ {"id":"12345", "quantity": 1}, {"id":"amnsdf", "quantity": 3}, ] } }

Description of “user” object:

Attribute	Description	Type Example	Required
email	User email address	[string] [email protected]	required
tel	User Phone number	[string] 0760000000	optional
firstname	User First Name	[string] John	optional
lastname	User lastname	[string] Doe	optional
country	User country	[string] United States	optional
city	User city	[string] Boston	optional

Description of “event” object.

It has a single key: “confirmation” which represents the event type. The value of “confirmation” attribute is a dict with the following attributes and values

Attribute	Description	Type & Example	Required
generic	Object with extra information for the event	[object]	required
generic.orderId	Unique order ID	[string] knssf22	required
generic.total	Total value of the purchase, including shipping.	[float] 435.00	required
generic.coupons	List of coupon codes used, as strings	[list] of strings [“coupon1”, “all10”]	optional
generic.currency	Currency. Format is 3 letter ISO code: “USD”, “EUR”, “RON”	[string] EUR	optional
generic.total_shipping	Total value paid for shipping	[float] 12.00	optional
generic.phone	Phone number provided by the user for this order	[string] 0760000000	optional
items	List of items that were purchased and their quantity. Each value is described below	[list] of objects	optional
item	Object with “id” and “quantity” keys. – ID represent item identifier, the same from product feed and other site events. – quantity (self explained)

Notes:

• while list of items is optional, we strongly recommend sending this information
• missing orderId won’t generate an error but it’s needed to uniquely add orders to an user
• api key is used for authenticating requests and is found under each account settings

Responses

The server responds with 200 status code if data was successfully received with the following content:

{
  "results": {
    "message": "Event created",
    "email": "Event was created for the specified user"
  }
}

Any status code other than 200 indicates an error occurred.

{
  "errors": [
    {
      "message": "Missing event information",
      "description": "Please send event information along with user",
    }
  ]
}

Recommendations:

Please send orders in realtime (when the thank you page loads) or within a minimum timeframe after customer placed the order.

Example requests:

{
    "user":
    {
        "email": "[email protected]",
        "tel": "07650000000"
    },
    "event":
    {
        "confirmation":
        {
            "generic":
            {
                "orderId": "unique_order_id",
                "total": 400.33,
                "status": "order_status",
                "coupons": ["coupon1", "coupon2"],
                "phone": "phone number",
                "currency": "RON",
                "total_shipping": 22.00
            },
            "items": [
            {
                "id": "12345",
                "quantity": 1
            },
            {
                "id": "amnsdf",
                "quantity": 3
            } ]
        }
    }
}

Example of a valid request

Document History

Version 1 – Feb 2 2024

• Initial version, based on existing API documentation