Klaviyo

Last updated April 19th at 8:09am

Klaviyo is a CRM plugin in Centra. The core functionality is sending events to Klaviyo that can be used for transactional emails and email marketing automation with language based customization. In your Klaviyo account, you can apply various advanced segmentation strategies based on event data and customer information that is synchronized from Centra to Klaviyo.

Click here to learn more about how to start using Klaviyo.

The recommended setup is a single Klaviyo account and single store plugin for all markets that are enabled in Centra.

Flow#

You set up your Klaviyo account's API credentials (API key & API private key) and settings in Klaviyo store plugin.
When store plugin is configured properly, Centra will start sending events to Klaviyo.
In Klaviyo account you can setup flows triggered off of the certain event types (metrics).

Setup in Centra#

Store plugin settings view in Centra AMS:

//a.storyblok.com/f/233206/b4980fde40/store_plugin.png

API key & API private key#

Copy the values of the API keys from https://www.klaviyo.com/account#api-keys-tab to store plugin configuration in Centra.

Base currency#

Currency used as a default currency in Klaviyo account. This currency will be used in all reports across the account. All the synchronized events will also contain price values in customer currency so that they can be used in all sorts of email communication.

Language selected from#

Delivery country - language will be matched based on customer's delivery country.
Site language - language selected by customer or matched by geo ip in webshop

Use short product name#

Include variant name in product name.

Product image size#

Image size you want to send over to Klaviyo for all the products. Select a proper image size that works for your product catalog.

Cart link#

Cart link: should be set to the URL your webshop uses for cart abandonment, e.g. https://example.com/abandoned-cart/{selection}

Newsletter lists to which customers will be opted in. Also, our integration will check this list in context of customer opt-out. In case of opt-out newsletter setting on customer profile in Centra will be updated. Customer can opt-in (subscribe and resubscribe) through API, by newsletter endpoint, and while placing the order. As a Centra user, you can save customer profile with setting Newsletter: Yes. You can create/find existing lists in Klaviyo Dashboard, under Audience -> Lists & Segments, type: Lists.

Product page URL#

If in the email communication you want to use product page URL, the ways of providing it might depend on the use case.

Product page URL in back in stock emails

For this use case the workflow is the following:

Go to your Klaviyo store plugin settings in Centra and fill in Product page URL setting. Example value https://demo-shop-test.centra.systems/product/{display_uri}
Product page URLs will be sent when catalog products are synchronized to Klaviyo, formatted with following pattern: configured Product page URL + display_uri from Centra. For example where display_uri is test-product-sv, the final product url sent to Klaviyo would be https://demo-shop-test.centra.systems/product/test-product-sv

Note that base URL specified in Product page URL needs to be controlled by your Frontend. Frontend needs to be able to route to the proper product page based on formatted value including display uri from Centra.

//a.storyblok.com/f/233206/29c94efc8e/product_url_store_setting.png

Product page URL in transactional email events (like Placed Order, Confirmed Order, Shipping Update, etc.)

For this use case there are 2 ways of achieving this:

The same way as described in previous use case for back in stock emails.
Pass the product page URL from the Frontend when the product is added to the selection using productUrl parameter in

Historical data export#

Our integration allow you to export your data to Klaviyo. This action base on customer account, and customer account is main entrance to data. What does it mean? By choosing date in Transfer historical date starting from, you are choosing the date in history when the customer account was created. For example, from the image below, customer accounts newer than (or exactly this date) 01-09-2022 00:00:00 will be transferred to Klaviyo.

In the Synchronization status line, you will see current transfer status.

When synchronization is pending, you will not be able to set it up again. Synchronization settings are in read mode only:

//a.storyblok.com/f/233206/696a9e17d1/historical_data_pending.png

During data export, the following event types will be sent:

Placed Order
Ordered Product
Confirmed Order
Cancelled Order
Refunded Order

Product catalog synchronization#

You are able to run catalog synchronization with Klaviyo account. To run synchronization, in Klaviyo plugin, change Synchronize product catalog to Klaviyo to Yes (default No) and save plugin.

In the Product catalog synchronisation status line, you will see current transfer status.

//a.storyblok.com/f/233206/880c167793/catalog_sync_plugin.png

Catalog synchronization cannot be run simultaneously with historical data export or during historical data import. Please wait until the end of historical data synchronization to be able to run catalog synchronization.

You can browse synchronized products in your Klaviyo account here on your Klaviyo account.

//a.storyblok.com/f/233206/643c8f262f/product_list.png

Catalog updates synchronization

We run updates synchronization right after saving the product in Centra, but this may take a while to see changes in Klaviyo catalog.

BackInStock category of products#

If you're using back in stock feature with Klaviyo plugin, virtual products might appear on your list with the following title format {productName} - [DO NOT USE][Back in stock automation]. They also have a special category assigned - BackInStock automation Those are products created merely for the purpose of back in stock subscription and are not supposed to be used in any emails using catalog lookup function, so you can ignore them.

You can run full synchronization more than once if needed, but in general synchronization of changes should be handled automatically.

Catalog product data reference#

{
    "external_id" : "1",
    "title" : "Test Product",
    "description" : "desc",
    "url" : "http://localhost/product/test-product",
    "image_thumbnail_url" : "http://localhost/client/dynamic//images/1_9adfeff6f2-red-amsbig.jpg",
    "image_full_url" : "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
    "custom_metadata" : {
        "ProductName": {
            "default": "Test Product",
            "de": "Produkt testen"
        },
        "VariantName": {
            "default": "Red",
            "de": "Rot"
        },
        "Description": {
            "default": "Product description",
            "de": "Produkt bezeichnung"
        },
        "CanonicalCategory": {
            "sv": "Handla",
            "en": "Shop",
            "de": "Shop",
            "default": "Shop"
        },
        "Price": {
            "USD": 9.00,
            "SEK": 100,
            "JPY": 32400
        },
        "Brand": "Brand",
        "Collection": "Collection",
        "ProductType": "product"
    }
}

Top-level product id in product catalog

Top-level catalog product id is a display item identifier from Centra. This is also matching the id of the order items that are send along with events for all the metrics (e.g. Placed Order or Ordered Product). Display item in Centra is a variant activated on a display, the concept is described in details here.

Back in stock subscriptions#

In order to enable back in stock feature you need to perform initial product catalog synchronisation first. Once it's done you can enable back in stock and access product catalog information in back in stock emails using catalog lookup feature.

//a.storyblok.com/f/233206/97a9db58b8/back_in_stock_disabled.png

//a.storyblok.com/f/233206/958eb8ddb8/back_in_stock_enabled.png

Back in stock requires frontend implementation against Checkout API or Shop API. The specification of endpoint is available in our swagger docs:

Back in stock flow

POST request towards Checkout API/Shop API

POST https://centra-instance.com/api/checkout-api/back-in-stock-subscription
{   
    "item": "12366-23400",
    "shipTo": {
        "country": "SE"
    },
    "email": "test@email.com",
    "language": "sv"
}

Centra creates back in stock product

Back in stock products are assigned with a special category and are supposed to be used only for internal purposes of back in stock automation. Concept of back in stock products is described in details here.

Back in stock product identifier consists of multiple parts, which on the example of 12366_SE_00 are:

12366 - display item id in Centra, which is top-level product identifier in Klaviyo
SE - ISO code of ship-to location country
00 - ISO code of ship-to location state (Sweden does not have states, placeholder 00 is used)

//a.storyblok.com/f/233206/545a34f128/back_in_stock_product.png

Centra creates back in stock variant

Variants are divided across ship-to locations supported in your retail store and across available sizes. Variant identifier consists of multiple parts, which on the example of 12366_SE_00_23400 are:

12366 - display item id in Centra, which is top-level product identifier in Klaviyo
SE - ISO code of ship-to location country
00 - ISO code of ship-to location state (Sweden does not have states, placeholder 00 is used)
23401 - size identifier in Centra

//a.storyblok.com/f/233206/549f9a99a1/back_in_stock_variant.png

Centra sends customer's back in stock subscription towards variant

To see active back in stock subscriptions in Klaviyo go to Back In Stock Report

//a.storyblok.com/f/233206/5bb2753a33/back_in_stock_report.png

Transactional emails#

Supported metrics#

Metric types currently supported by Centra:

Reset Password
Created Account
Placed Order
Ordered Product
Confirmed Order
Cancelled Order
Shipping Update
Refunded Order
Gift Certificate
Started Checkout
Changed Subscription Status
Failed Subscription Payment
Failed Subscription Payment Update
Successful Subscription Payment Update

Sending sample data to Klaviyo

You can send sample events to Klaviyo directly from store plugin configuration in Centra by clicking on link presented on the screenshot below. This will populate supported metrics listed above in your Klaviyo account and you will be able to browse sample data in the activity dashboard.

After synchronisation of sample data you can remove sample profile so that the data does not affect any reporting functionalities.

//a.storyblok.com/f/233206/c1f566cdf7/sample_data_link.png

//a.storyblok.com/f/233206/22594cf984/sample_data_popup.png

Transactional flows configuration#

In Klaviyo transactional and non-transactional automation is triggered off of the same metrics (events). In order to setup transactional flows in Klaviyo refer to the following guide. When plugin is activated, Centra will start sending all the supported types of metrics when events occur, but you can choose which ones you want to listen to in your flows setup on your Klaviyo account.

Extra metrics for manual resend email from Centra, with exactly the same data as regular ones, but requires own event type:

Placed Order - resend
Confirmed Order - resend
Cancelled Order - resend
Shipping Update - resend
Refunded Order - resend
Gift Certificate - resend

Listed metrics for the email resend purposes require additional email trigger configuration for email resending to work. Resend metrics listed above will not impact flows and reporting based on regular metrics.

When creating a flow for a certain metric in Klaviyo, tags need to be matching the tags listed above.

List of all the synchronised events is visible in your account's activity feed:

//a.storyblok.com/f/233206/b93d5b4d32/activity_feed.png

When at least one event with a certain metric is sent to Klaviyo, you can choose it from the dropdown in create flow view:

//a.storyblok.com/f/233206/67e59bd028/create_flow.png

Configuring email templates#

In order to send transactional email content in the language of the customer you will need one email template per supported language. To make it work, proper conditions based on profile's language need to be added.

Example flow for Placed Order event could look like this:

//a.storyblok.com/f/233206/0ad7fc7dd2/conditional_flow.png

In the synchronised events data, Centra is sending prices both in base currency selected in Centra store plugin and in customer currency. In the email template following variables should to be used in order to use prices in customer currency in the email communication:

Item level variables:

{{ item.GrossPaidPricePerUnitInCustomerCurrency }} - item price per piece in customer currency
{{ item.GrossPaidPriceInCustomerCurrency }} - price for item line in customer currency
{{ item.TaxAmountInCustomerCurrency }} - tax amount per item in customer currency
{{ item.DiscountValueInCustomerCurrency }} - discounted value in customer currency
{{ item.OriginalPriceInCustomerCurrency }} - original price for item line in customer currency

Event level variables:

{{ event.GrossPaidPriceInCustomerCurrency }} - order total in customer currency
{{ event.TaxAmountInCustomerCurrency }} - order total in customer currency
{{ event.DiscountValueInCustomerCurrency }}- discount total in customer currency

You can browse all the item and event level variables on the details of certain event in activity feed.

Catalog product data in template

To find full documentation about building email template in Klaviyo please check Klaviyo template guide.

Localized product data

Our Klaviyo plugin allows you to send localized data with your emails. Translated multi-language fields and multi-currency prices are send as JSON strings from which you can extract proper values using built in email template functions. You can use static lookup (like |lookup:"SEK") or more dynamic, based on variable (like |lookup:customer_lang)

{% catalog event.ItemID %}
    {% with customer_lang=person|lookup:"Language" %}
        {% with customer_currency=person|lookup:"Currency" %}
            Description: {{ catalog_item.metadata.Description|lookup:"default"}}  
            Title: {{ catalog_item.title }}  

            Static price in SEK: {{ catalog_item.metadata|lookup:"Price"|string_to_object|lookup:"SEK"}}
            Dynamic product name in customer language: {{ catalog_item.metadata|lookup:"ProductName"|string_to_object|lookup:customer_lang}}
            Dynamic price in customer currency: {{ catalog_item.metadata|lookup:"Price"|string_to_object|lookup:customer_currency}}
        {% endwith %}
    {% endwith %}
{% endcatalog %}

Back-in-stock example flow configuration

Catalog lookup tag can be also used to pull product data from catalog in back in stock emails. In order to fetch product information, top-level product id needs to be extracted from VariantID.

Following snippet will split the compound VariantID like 12366_SE_00_23400 and use extracted top-level product id 12366 to fetch catalog product data.

{% with idParts=event.VariantId|split:"_" %}
{% catalog idParts.0 %}
    <p>The {{ catalog_item.title }} Is Back!</p>
{% endcatalog %}
{% endwith %}

Due to 2-level product model in Klaviyo in order to access complete set of fields useful for back in stock emails you will need to access both product level and variant level data. Below you will find a list of commonly requested fields and how to access them.

In below list catalog_item refers to the back in stock parent product that is pulled by extracting top-level product id from VariantID like in snippet above.

display name {{ event.VariantName }}
size name {{ event.SKU|split:" "|last }}
product url {{ catalog_item.url }}
product image (thumbnail) {{ catalog_item.featured_image.thumbnail.src }}
product image (full) {{ catalog_item.featured_image.full.src }}
product price (in customer currency) {% with customer_currency=person|lookup:"Currency" %}{{ catalog_item.metadata|lookup:"Price"|string_to_object|lookup:customer_currency }}{% endwith %}

Example structure of email and accessing fields listed above:

{% with idParts=event.VariantId|split:"_" %}
{% catalog idParts.0 %}
  <p>The {{ catalog_item.title }} Is Back!</p>
  <p>Custom description: {{ catalog_item.metadata.Description }}</p>
  <p>Product image: {{ catalog_item.featured_image.full.src }}</p>
  <p>Size: {{ event.SKU|split:" "|last }}</p>
  <p>Price in customer currency:
        {% with customer_currency=person|lookup:"Currency" %}
            {{ catalog_item.metadata|lookup:"Price"|string_to_object|lookup:customer_currency }} 
        {% endwith %}</p>
{% endcatalog %}
{% endwith %}

Event data reference#

Confirmed Order, Refunded Order

{
    "$event_id": 102,
    "$value": 215,
    "CustomerCurrency": "EUR",
    "GrossPaidPriceInCustomerCurrency": "215.00",
    "TaxAmount": "43.00",
    "TaxAmountInCustomerCurrency": "43.00",
    "Categories": [
        "shop"
    ],
    "ItemNames": [
        "Test Product"
    ],
    "Brands": [
        "Brand"
    ],
    "DiscountValue": "0.00",
    "Items": [
        {
            "ProductID": "1-1",
            "SKU": "123456789",
            "ProductName": "Test Product",
            "Quantity": 2,
            "VariantName": "Blue jeans",
            "GrossPaidPrice": "200.00",
            "GrossPaidPriceInCustomerCurrency": "200.00",
            "OriginalPrice": "200.00",
            "OriginalPriceInCustomerCurrency": "200.00",
            "GrossPaidPricePerUnit": "100.00",
            "GrossPaidPricePerUnitInCustomerCurrency": "100.00",
            "ProductURL": "",
            "ImageURL": "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
            "Categories": {
                "1": "shop"
            },
            "Brand": "Brand",
            "TaxAmount": "40.00",
            "TaxAmountInCustomerCurrency": "40.00",
            "TaxPercent": 25,
            "Discounted": false,
            "DiscountValue": "0.00",
            "DiscountValueInCustomerCurrency": "0.00",
            "ProductType": "product"
        }
    ],
    "BillingAddress": {
        "FirstName": "Jane",
        "LastName": "Doe",
        "Company": "Centra",
        "Address1": "Sveavägen 9",
        "Address2": "Address Two",
        "City": "Stockholm",
        "Region": "",
        "Region_code": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "111 57",
        "Phone": "123456789",
        "Email": "test@centra.com"
    },
    "ShippingAddress": {
        "FirstName": "Jane",
        "LastName": "Doe",
        "Company": "Centra",
        "Address1": "Sveavägen 9",
        "Address2": "Address Two",
        "City": "Stockholm",
        "Region": "",
        "Region_code": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "111 57",
        "Phone": "123456789",
        "Email": "test@centra.com"
    },
    "Shipping": {
        "Method": "pnl-bua (Ingrid)",
        "Service": "pnl-bua (Ingrid)",
        "Carrier": "",
        "CentraShippingMethod": "SEK",
        "Cost": "10.00",
        "CostInCustomerCurrency": "10.00",
        "TaxAmount": "2.00",
        "TaxAmountInCustomerCurrency": "2.00"
    },
    "MethodForPayment": "dummy"
}

ProductType variable in Item object can take one of two values: "product" or "bundle".

Value of Shipping.Method field is concatenated string of Shipping.Service and Shipping.Carrier, when Shipping.Service and Shipping.Carrier fields are empty we use Shipping.CentraShippingMethod value. Shipping.Service and Shipping.Carrier fields are present when shipment has been completed - value of these fields in most cases will be available on Shipping Update event.

Additional shipping fields for Confirmed Order available when Ingrid shipping plugin is enabled and order was placed with this plugin.

{
    [...],
    "Shipping": {
        [...],
        "IngridPickupPointAddress": "Grepgatan 40, 25448 Helsingborg, SE",
        "IngridExpectedDeliveryDate": "2022-11-09 - 2022-11-10",
        "IngridCarrier": "Instabox",
        "IngridProduct": "Instabox Express",
        "IngridShippingMethod": "isb-express"
    }
}

Placed Order

Placed Order event data structure is the same as for Confirmed Order and Refunded Order events but with extra field OrderType

{
    [...],
    "OrderType": "One-time Purchase"
}

OrderType variable in Item object can take one of three values:

"One-time Purchase" (for one-time orders)
"New Subscription" (for newly started subscriptions)
"Recurring Subscription Payment" (for renewal or recurring orders for pre-existing subscriptions)

"New Subscription" type of order will contain additional properties with subscription information on items purchased in subscription model. See Subscription orders section for more information.

Additional shipping fields available when Ingrid shipping plugin is enabled and order was placed with this plugin.

{
    [...],
    "Shipping": {
        [...],    
        "IngridPickupPointAddress": "Grepgatan 40, 25448 Helsingborg, SE",
        "IngridExpectedDeliveryDate": "2022-11-09 - 2022-11-10",
        "IngridCarrier": "Instabox",
        "IngridProduct": "Instabox Express",
        "IngridShippingMethod": "isb-express"
    }
}

Ordered Product

Ordered Product is not a transactional type of metric, but is used for the purposes of personalized recommendations and segmenting customers based on the items they purchase. They can also be used to create product-specific up-sell and cross-sell flows. They include detailed information about item that has been purchased.

Ordered Product: this metric is tracked when a customer places an order. NOTE: One Ordered Product event is tracked for each item purchased. If someone purchases three items in a single order, there will be one Placed Order event and three corresponding Ordered Product events recorded.

{
    "$event_id": "551-ABCDEFGHIJKL-1",
    "$value": 100,
    "OrderId": "551",
    "ProductID": 1,
    "SKU": "123456789",
    "ProductName": "Test Product",
    "Quantity": 1,
    "GTIN": "ABCDEFGHIJKL",
    "Size": "",
    "VariantName": "Red",
    "GrossPaidPrice": "100.00",
    "GrossPaidPriceInCustomerCurrency": "100.00",
    "OriginalPrice": "100.00",
    "OriginalPriceInCustomerCurrency": "100.00",
    "GrossPaidPricePerUnit": "100.00",
    "GrossPaidPricePerUnitInCustomerCurrency": "100.00",
    "ProductURL": "https://test.com/product/test-product",
    "ImageURL": "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
    "Categories": [
      "shop"
    ],  
    "Brand": "Brand",
    "TaxAmount": "20.00",
    "TaxAmountInCustomerCurrency": "20.00",
    "TaxPercent": "25.00",
    "Discounted": false,
    "DiscountValue": "0.00",
    "DiscountValueInCustomerCurrency": "0.00",
    "ProductType": "product"
}

ProductType variable in event data can take one of two values: "product" or "bundle".

Started Checkout

Started Checkout event data structure is the same as for Confirmed Order and Refunded Order events but with extra field “AbandonedCartURL”

{
    [...],
    "AbandonedCartURL": "https://example.com/abandoned-cart/{selection}"
}

Cancelled Order

Cancelled Order event data structure is the same as for Confirmed Order and Refunded Order events but with extra field “Reason”

{
    [...],
    "Reason": "Size too small"
}

Shipping Update

{
    "$event_id": "Shipped-113-1",
    "OrderId": 113,
    "ShipmentId": "Shipped-113-1",
    "UpdateType": "Shipped",
    "Items": [
        {
            "ProductID": 1,
            "SKU": "123456789",
            "ProductName": "Test Product",
            "Quantity": 1,
            "GTIN": "ABCDEFGHIJKL",
            "Size": "",
            "VariantName": "Red",
            "GrossPaidPrice": "100.00",
            "GrossPaidPriceInCustomerCurrency": "100.00",
            "OriginalPrice": "100.00",
            "OriginalPriceInCustomerCurrency": "100.00",
            "GrossPaidPricePerUnit": "100.00",
            "GrossPaidPricePerUnitInCustomerCurrency": "100.00",
            "ProductURL": "",
            "ImageURL": "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
            "Categories": {
                "1": "shop"
            },
            "Brand": "Brand",
            "TaxAmount": "20.00",
            "TaxAmountInCustomerCurrency": "20.00",
            "TaxPercent": "25.00",
            "Discounted": false,
            "DiscountValue": "0.00",
            "DiscountValueInCustomerCurrency": "0.00",
            "ProductType": "product"
        }
    ],
    "ShippingAddress": {
        "FirstName": "Jane",
        "LastName": "Doe",
        "Company": "Centra",
        "Address1": "Sveavägen 9",
        "Address2": "Address Two",
        "City": "Stockholm",
        "Region": "",
        "Region_code": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "111 57",
        "Phone": "123456789",
        "Email": "test@centra.com"
    },
    "ShippingMethod": "EUR",
    "ShippingService": "",
    "ShippingCarrier": "",
    "CentraShippingMethod": "SEK",
    "TrackingNumber": "ABC123",
    "TrackingUrl": "https://test-tracking-delivery.com/ABC123",
    "PackagesAmount": 1,
    "ShippingDate": "2022-09-28 15:12:57",
    "MethodForPayment": "Third Party Payment",
    "CustomerCurrency": "EUR",
    "GrossPaidPrice": "215.00",
    "GrossPaidPriceInCustomerCurrency": "215.00",
    "TaxAmount": "43.00",
    "TaxAmountInCustomerCurrency": "43.00", 
    "DiscountValue": "0.00",
    "DiscountValueInCustomerCurrency": "0.00",
    "ShippingCost": "0.00",
    "ShippingCostInCustomerCurrency": "0.00",
    "ShippingTaxAmount": "0.00",
    "ShippingTaxAmountInCustomerCurrency": "0.00",
    "OrderDate": "2022-11-11 21:37:00"
}

Value of ShippingMethod field is concatenated string of ShippingService and ShippingCarrier, when ShippingService and ShippingCarrier fields are empty we use CentraShippingMethod value. ShippingService and ShippingCarrier fields are present when shipment has been completed - value of these fields in most cases will be available on Shipping Update event.

Additional shipment fields available when Ingrid shipping plugin is enabled and order was placed with this plugin.

{
    [...]
    "IngridMethod": "pnl-bua",
    "IngridConvertedId": "PickupPoint",
    "IngridPickup": "123",
    "IngridDoorCode": "",
    "IngridDeliveryTime": "2022-11-11",
    "IngridCourierInstruction": "",
    "IngridPickupPointAddress": "Grepgatan 40, 25448 Helsingborg, SE",
    "IngridExpectedDeliveryDate": "2022-11-09 - 2022-11-10",
    "IngridCarrier": "Instabox",
    "IngridProduct": "Instabox Express",
    "IngridShippingMethod": "isb-express"
}

Gift Certificate

{
    "$eventId": "123",
    "Name": "Some name",
    "Code": "Some_code",
    "Link": "https://test.com/",
    "Message": "Hello there!",
    "Date": "2022-01-01 00:00:00",
    "DueDate": "2022-01-01 00:00:00",
    "Description": "Your gift card!",
    "Friend": "Jane Doe",
    "$value": "100.00",
    "ValueInCustomerCurrency": "100.00",
    "CustomerCurrency": "EUR"    
}

Reset Password

{
    "$event_id": "123",
    "PasswordResetLink": "https://localhost/password-reset?[...]"
}

Changed Subscription Status

{
    "$event_id": "1-1666600262",
    "PaymentType": "cc",
    "PaymentDescription": "Mastercard",
    "ShippingCostInCustomerCurrency": 0,
    "Reason": "manual user change",
    "OldStatus": "active",
    "NewStatus": "active",
    "Subscription": {
        "SubscriptionId": 1,
        "CreatedAt": "2022-10-24 10:31:02",
        "IntervalType": "day",
        "IntervalValue": 30,
        "IntervalFormatted": "Every 30 days",
        "DiscountPercent": 0
    },
    "SubscriptionContractAddress": {
        "FirstName": "Jane",
        "LastName": "Doe",
        "Company": "",
        "Address1": "Sveavägen 9",
        "Address2": "",
        "City": "Stockholm",
        "Region": "",
        "RegionCode": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "111 57",
        "Phone": "+4687203333",
        "Email": "support@centra.com"
    }
}

Failed Subscription Payment

{
    "$event_id": "11-12-1666600262",
    "PaymentType": "cc",
    "PaymentDescription": "Mastercard",
    "ShippingCostInCustomerCurrency": 0,
    "Subscriptions": [
        {
            "SubscriptionId": 1,
            "CreatedAt": "2022-10-24 10:31:02",
            "IntervalType": "day",
            "IntervalValue": 30,
            "IntervalFormatted": "Every 30 days",
            "DiscountPercent": 0
        }
    ],
    "SubscriptionContractAddress": {
        "FirstName": "Jane",
        "LastName": "Doe",
        "Company": "",
        "Address1": "Sveavägen 9",
        "Address2": "",
        "City": "Stockholm",
        "Region": "",
        "RegionCode": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "111 57",
        "Phone": "+4687203333",
        "Email": "support@centra.com"
    },
    "ManageSubscriptionPaymentMethodsUrl": "https://example.com/subscription/payment/?id=123"
}

Failed Subscription Payment Update and Successful Subscription Payment Update

{
  "$event_id": "11-1666600262",
  "SubscriptionContractId": 11,
  "PaymentType": "cc",
  "PaymentDescription": "Mastercard",
  "ShippingCostInCustomerCurrency": 0,
  "Subscriptions": [
    {
      "SubscriptionId": 1,
      "CreatedAt": "2022-10-24 10:31:02",
      "IntervalType": "day",
      "IntervalValue": 30,
      "IntervalFormatted": "Every 30 days",
      "DiscountPercent": 0
    }
  ],
  "SubscriptionContractAddress": {
    "FirstName": "Jane",
    "LastName": "Doe",
    "Company": "",
    "Address1": "Sveavägen 9",
    "Address2": "",
    "City": "Stockholm",
    "Region": "",
    "RegionCode": "",
    "Country": "Sweden",
    "CountryCode": "SE",
    "Zip": "111 57",
    "Phone": "+4687203333",
    "Email": "support@centra.com"
  },
  "ManageSubscriptionPaymentMethodsUrl": "https://example.com/subscription/payment/?id=123"
}

Subscription orders#

Placed Order event supports 3 OrderType values:

One-time Purchase (for one-time orders)
New Subscription (for newly started subscriptions)
Recurring Subscription Payment (for renewal or recurring orders for pre-existing subscriptions)

Only OrderType of value New Subscription contains additional subscription information included on event item level. Item level boolean property item.IsSubscription can be used to dynamically render or skip additional item.Subscription.* properties containing subscription information.

Centra allows for combining subscription purchases with one time purchases in single checkout. Example payload of Placed Order event created as a result of such combined checkout:

{
    "OrderId": "123",
    "CustomerCurrency": "SEK",
    "GrossPaidPriceInCustomerCurrency": "200.00",
    "TaxAmount": "40.00",
    "TaxAmountInCustomerCurrency": "40.00",
    "Categories": [
        "shop"
    ],
    "ItemNames": [
        "Test Product"
    ],
    "Brands": [
        "Brand"
    ],
    "DiscountValue": "0.00",
    "DiscountValueInCustomerCurrency": "0.00",
    "Items": [
        {
            "ProductID": 1,
            "SKU": "123456789",
            "ProductName": "Test Product",
            "Quantity": 1,
            "GTIN": "ABCDEFGHIJKL",
            "Size": "",
            "VariantName": "Red",
            "GrossPaidPrice": "100.00",
            "GrossPaidPriceInCustomerCurrency": "100.00",
            "OriginalPrice": "100.00",
            "OriginalPriceInCustomerCurrency": "100.00",
            "GrossPaidPricePerUnit": "100.00",
            "GrossPaidPricePerUnitInCustomerCurrency": "100.00",
            "ProductURL": "",
            "ImageURL": "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
            "Categories": {
                "1": "shop"
            },
            "Brand": "Brand",
            "TaxAmount": "20.00",
            "TaxAmountInCustomerCurrency": "20.00",
            "TaxPercent": "25.00",
            "Discounted": false,
            "DiscountValue": "0.00",
            "DiscountValueInCustomerCurrency": "0.00",
            "Subscription": {
                "NextOrderDate": "2022-11-12",
                "DiscountPercent": 0,
                "IntervalType": "month",
                "IntervalValue": 1,
                "IntervalFormatted": "every 1 month"
            },
            "IsSubscription": true
        },
        {
            "ProductID": 1,
            "SKU": "123456789",
            "ProductName": "Test Product",
            "Quantity": 1,
            "GTIN": "ABCDEFGHIJKL",
            "Size": "",
            "VariantName": "Red",
            "GrossPaidPrice": "100.00",
            "GrossPaidPriceInCustomerCurrency": "100.00",
            "OriginalPrice": "100.00",
            "OriginalPriceInCustomerCurrency": "100.00",
            "GrossPaidPricePerUnit": "100.00",
            "GrossPaidPricePerUnitInCustomerCurrency": "100.00",
            "ProductURL": "",
            "ImageURL": "http://localhost/client/dynamic/images/1_9adfeff6f2-red.jpg",
            "Categories": {
                "1": "shop"
            },
            "Brand": "Brand",
            "TaxAmount": "20.00",
            "TaxAmountInCustomerCurrency": "20.00",
            "TaxPercent": "25.00",
            "Discounted": false,
            "DiscountValue": "0.00",
            "DiscountValueInCustomerCurrency": "0.00"
        }
    ],
    "BillingAddress": {
        "FirstName": "Test Billing",
        "LastName": "Testson Billing",
        "Company": "",
        "Address1": "Address One",
        "Address2": "Address Two",
        "City": "Malmo",
        "Region": "",
        "Region_code": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "12345",
        "Phone": "123456789",
        "Email": "hubert.strychalski@centra.com"
    },
    "ShippingAddress": {
        "FirstName": "Test Billing",
        "LastName": "Testson Billing",
        "Company": "",
        "Address1": "Address One",
        "Address2": "Address Two",
        "City": "Malmo",
        "Region": "",
        "Region_code": "",
        "Country": "Sweden",
        "CountryCode": "SE",
        "Zip": "12345",
        "Phone": "123456789",
        "Email": "hubert.strychalski@centra.com"
    },
    "Shipping": {
        "Method": "SEK",
        "Service": "",
        "Carrier": "",     
        "CentraShippingMethod": "SEK",
        "Cost": "0.00",
        "CostInCustomerCurrency": "0.00",
        "TaxAmount": "0.00",
        "TaxAmountInCustomerCurrency": "0.00"
    },
    "MethodForPayment": "Third Party Payment",
    "CreatedDate": "2022-10-12 12:52:03",
    "OrderType": "New Subscription",
    "$value": 200
}

Example flow trigger configuration with recurring orders support#

OrderType of values One-time Purchase and Recurring Subscription Payment are combined in the single flow as those do not contain any additional subscription information.

OrderType of value New Subscription is processed by separate flow because it contains additional subscription data.

//a.storyblok.com/f/233206/a599ba2410/subscription_transactional_triggers.png

When newsletter list is selected in store plugin settings Centra will push newsletter list subscriptions to Klaviyo when newsletter opt-in is received in Centra in one of the following ways:

Checkout API/Shop API newsletter subscribe endpoints
Newsletter field update on customer level
Newsletter opt-in during checkout

Additionally, once a day global unsubscribes and selected list unsubscribes will be fetched from Klaviyo API and newsletter flag on customer level in Centra will be updated accordingly.

Centra does not fetch newsletter list subscriptions that were made outside of Centra's control e.g. CSV import to Klaviyo based on data exported from another integration or direct integration to Klaviyo working ouside of Centra.

In order to keep the opt-in status in sync with Klaviyo we recommend sending customer newsletter subscriptions to Checkout API/Shop API newsletter endpoints:

Checkout API: swagger documentation
Shop API: swagger documentation

Centra does not subscribe customers to selected newsletter list during historical data transfer. If you want to transfer newsletter subscriptions from Centra to Klaviyo in bulk, you can export newsletter list from Centra and import customers to newsletter list in Klaviyo using CSV import. CSV import in Klaviyo allows to safely import newsletter list subscriptions without triggering any email communication.

//a.storyblok.com/f/233206/e667dd1c2d/customer_newsletter_export.png

If you want to send out campaign emails for a list that contains customers with different languages you can either:

Dynamically render localized content based on customer profile language using a single template.
Configure separate campaign with static template for each language on the list using segment exclusions.

Example for method 2:

Segment excluding non-Swedish speaking customers:

//a.storyblok.com/f/233206/6ecfbee580/segment_example.png

Campaign targeted for Swedish speaking customers:

//a.storyblok.com/f/233206/773081a150/example_campaign_swedish.png

Activity tracking#

Although as headless platform, Centra does not control activity tracking through integration with Klaviyo it is still possible to send activity tracking events directly from the website.

You can track following events:

Active on Site
Added to Cart
Viewed Product

For Added to Cart and Viewed Product events you should use the same top level product id that is used on events sent directly from Centra. You can find more information about it here.

For authorization public api key should be used. You can find details about activity tracking implementation in Klaviyo documentation section.