Tracking checkout changes

Tracking checkout changes is what makes Abandoned Checkout automations possible. Each checkout event tells Customer Engagement what a visitor is about to buy: the products, prices, discounts, coupon, and whether they have selected a shipping and payment method. Every event is tied to a cart through cartRef, and to a contact through contactId or the visitor’s identification cookie. You can send checkout data either with the tracking script or with the tracking API.

How it works

Your site submits every checkout change, via the tracking script or the tracking API.
A checkout that still contains products and hasn’t been touched for 30 minutes is treated as abandoned. If it is connected to a contact, it is sent to Customer Engagement. All other checkouts are filtered out.
Customer Engagement enriches the products from the product feed and triggers the Abandoned Checkout automation matching the checkout’s locale.

Checkout, cart and product views in one session

Checkout works together with cart changes and product views. Customer Engagement uses the sessionId to identify the winning “abandoned” signal for a session. If a single abandoned session contains all three event types (checkout, cart and product view), only one Abandoned Checkout signal is produced, not one per event type. To get this right, send the events from the same session with the same sessionId. The tracking script handles this for you. If you use the tracking API, you must include the sessionId yourself (see below).

Using the tracking script

Call checkout() every time the checkout state changes: an item is added, removed or updated, a coupon is applied, or the visitor selects a shipping or payment method. Call it whether or not the visitor has been identified.

Tracking a checkout

va("checkout", {
    "cartRef": "354354",
    "checkoutRef": "CHK-20931",
    "contactId": "afa7625d-2e97-4667-b4c1-ad3b01194bee",
    "cartUrl": "https://www.store.se/cart?id=354354",
    "checkoutUrl": "https://www.store.se/checkout?id=CHK-20931",
    "locale": "sv-SE",
    "currencyCode": "SEK",
    "coupon": "SUMMER10",
    "totalAmount": 1708.2,
    "totalDiscountAmount": 189.8,
    "shippingMethodSelected": true,
    "paymentMethodSelected": true,
    "items": [
        {
            "itemId": "456436",
            "quantity": 2,
            "index": 0,
            "salesPrice": 499.0,
            "totalSalesPrice": 998.0,
            "totalDiscount": 99.8,
            "totalSalesPriceAfterDiscount": 898.2,
            "category": "Women",
            "category2": "Shoes",
            "brand": "Acme"
        },
        {
            "itemId": "456437",
            "quantity": 1,
            "index": 1,
            "salesPrice": 899.0,
            "totalSalesPrice": 899.0,
            "totalDiscount": 89.9,
            "totalSalesPriceAfterDiscount": 809.1,
            "category": "Women",
            "category2": "Bags",
            "brand": "Acme"
        }
    ]
});

Checkout fields

string

required

The reference of the cart this checkout belongs to. Must be the same cartRef you use in cart events for that cart.

string

required

Your reference for this checkout. Must be unique per checkout and must never change for the life of that checkout. Maximum 255 characters. checkoutReference is accepted as an alias in the tracking script.

string

required

The locale of the site the checkout belongs to, as an IETF language tag such as sv-SE.

array<object>

required

The full current contents of the checkout.

string

A link back to the cart on your site.

string

A link back to this checkout on your site.

string

The Customer Engagement contact ID. Must be a valid GUID or short GUID, with a maximum of 36 characters. If omitted, the _vaI cookie is used as a fallback.

string

The coupon or discount code applied to the checkout. Maximum 100 characters.

number

The total amount of the checkout.

number

The total discount applied to the checkout.

string

The currency of all amounts, as a three-letter ISO 4217 code such as SEK. If provided, it must consist of exactly 3 letters.

boolean

Whether the visitor has selected a shipping method (true or false).

boolean

Whether the visitor has selected a payment method (true or false).

Item fields

string

required

The product identifier, matched against SKU in Customer Engagement. Maximum 255 characters.

int

required

The number of that item in the checkout. Must be an integer of 1 or greater.

int

The position of the item in the checkout. Must be 0 or greater. If omitted, the item’s position in the items array is used.

number

The unit price of the item.

number

The price of the item multiplied by its quantity, before discount.

number

The total discount applied to the item.

number

The total price of the item after discount.

string

The item’s main category. Use category2 to category5 for deeper levels of the category hierarchy. Maximum 100 characters per category field.

string

The item’s brand.

Using the tracking API

You can submit checkout changes directly via the API instead of implementing the tracking script. The API always requires a contactId, so it can only track identified visitors. Anonymous checkouts can only be tracked with the script. You are also responsible for identifying visitors who arrive from Customer Engagement email links yourself, by reading the vtid query parameter and passing it as contactId. You must also include a sessionId in every payload. It is required to identify the winning abandoned signal when a session contains checkout, cart and product view events. Use the same sessionId across all three event types. See sessions and sessionId. Send checkout events to the tracking/checkouts endpoint. You can test the calls from your OpenAPI (Swagger) page:

[tenantname].voyado.com/api/v3/ui/index#/tracking

Read about the Customer Engagement API and your OpenAPI page

Rules to follow

Send a checkout event only when the checkout actually changes. Firing events at other times, such as on page load or navigation, pollutes your data in Customer Engagement.

Every change means one event. Customer Engagement always works from the latest state, so the data you send must match what the checkout currently displays. Send the full contents every time, not just what changed.
checkoutRef must be unique and stable. Never share a checkoutRef between checkouts or visitors, and never change it for an existing checkout.
Use the same cartRef as your cart events. This is what links the checkout to the cart.
Always send locale, checkoutRef, cartRef and items. The script does not send the event if any of them is missing, and logs an error to the browser console.
Send valid items. Every item needs an itemId (255 characters or fewer) and an integer quantity of 1 or greater.
Use consistent currency and amounts. Send all amounts in the same currency, and set currencyCode to a 3-letter ISO 4217 code.
Use one sessionId per session across checkout, cart and product view events. This ensures a single Abandoned Checkout signal per abandoned session. With the tracking script this is handled for you; with the API you must send it yourself.
Call emptyCart() after a completed purchase. A checkout event does not clear the cart. If a visitor buys without your site calling emptyCart(), an active abandoned automation may still trigger for someone who has already bought. See tracking cart changes.

E-com and tracking

Campaigns

App push

Tracking checkout changes

How it works

Checkout, cart and product views in one session

Using the tracking script

Checkout fields

Item fields

Using the tracking API

Read about the Customer Engagement API and your OpenAPI page

Rules to follow

Verify your checkout tracking

​How it works

​Checkout, cart and product views in one session

​Using the tracking script

​Checkout fields

​Item fields

​Using the tracking API

Read about the Customer Engagement API and your OpenAPI page

​Rules to follow

Verify your checkout tracking

How it works

Checkout, cart and product views in one session

Using the tracking script

Checkout fields

Item fields

Using the tracking API

Rules to follow