ServerSide Integration

You are here:
Estimated reading time: 2 min

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.

Endpointhttps://api.vtcdn.net/v1/event/
Request TypePOST
HeadersAuthorization: api_key
HeadersContent-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:

AttributeDescriptionType ExampleRequired
emailUser email address[string] [email protected]required
telUser Phone number [string] 0760000000optional
firstnameUser First Name[string] Johnoptional
lastnameUser lastname[string] Doeoptional
countryUser country[string] United Statesoptional
cityUser city[string] Bostonoptional

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

AttributeDescriptionType & ExampleRequired
genericObject with extra information for the event[object]required
generic.orderIdUnique order ID[string] knssf22required
generic.totalTotal value of the purchase, including shipping. [float] 435.00required
generic.couponsList of coupon codes used, as strings[list] of strings [“coupon1”, “all10”]optional
generic.currencyCurrency. Format is 3 letter ISO code: “USD”, “EUR”, “RON”[string] EURoptional
generic.total_shippingTotal value paid for shipping[float] 12.00optional
generic.phonePhone number provided by the user for this order[string] 0760000000optional
itemsList of items that were purchased and their quantity. Each value is described below[list] of objectsoptional
itemObject 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
Was this article helpful?
Dislike 0
Views: 9