Identifying your top-spending customers

---

Solution Recipes are tutorials to achieve specific objectives in Klaviyo. They can also help you master Klaviyo, learn new third-party technologies, and come up with creative ideas. They are written mainly for developers and technically-advanced users. 

This is a guest post written by Elise Davis, senior technical writer @ Klaviyo, who recently built this as part of Klaviyo’s internal Solution Architect mentorship program.

Introduction

Klaviyo has powerful tools for calculating customer lifetime value (CLV), both historic (i.e., actual purchases minus returns/refunds) and predicted (i.e., potential future spend). You can use this data to target your most loyal customers with specialized messaging and treat them like the VIPs they are. 

This data is calculated automatically with Klaviyo’s predictive analytics tools, then stored as properties on a customer profile. You can access this data by exporting a list of contacts, or through the Profiles API endpoint. 

Challenge

CLV data is readily available to you in Klaviyo, but it can be challenging to identify the thresholds that set your best customers apart. This solution recipe will teach you how to identify your top customer groups (e.g., top 25% of customers based on historical spend). Once you’ve identified this threshold, use it to create segments to send personalized marketing to your most loyal contacts. 

Ingredients

1 Klaviyo account with purchase data synced from your store

500+ customers who have placed an order

180+ days of order history

2+ orders from the last 30 days

2+ customers who have placed 3 or more orders

Instructions

At a high level, the steps to execute this recipe are: 

1. Use the Klaviyo Profiles endpoint to pull the historic CLV for every profile in your account. This endpoint can pull up to 100 profiles at a time, so you’ll need to page through the data.
   https://a.klaviyo.com/api/profiles/?page[size]=100&additional-fields[profile]=predictive_analytics.historic_clv&fields[profile]=id 
2. Calculate the nth percentile of your non-zero CLVs (where n = the percentage of customers you want to identify, e.g., top 25%). 
3. Create a segment with the following definition:
   Properties about someone > Historic CLV > is at least ___
   Fill in the blank with the number found in step 2.
   
4. Repeat the steps and update your segment periodically (perhaps once a month), as your dataset changes with every new order placed on your site. 

I used Python to execute steps 1-2, using this script: 

import numpy as np
import requests


def calculate(api_key,threshold): 


    # API endpoint for accessing CLV data 
    url = "https://a.klaviyo.com/api/profiles/?page[size]=100&additional-fields[profile]=predictive_analytics.historic_clv&fields[profile]=id"


    headers = {
        "accept": "application/json",
        "revision": "2023-02-22",
        "Authorization": f"Klaviyo-API-Key {api_key}"
    }


    response = requests.get(url, headers=headers)
    historicClvs = []
    userPercentile = threshold # an integer 1-100 indicating the percent of customers who consistitue your "top" customers; i.e., 10 for the top 10% of customers


    # Get CLVs and add them to the historicClvs array
    def getPageCLV(payload):
        if not payload.json()['data']:
            payload.json()['data'] = []
        for person in payload.json()['data']:
            if person["attributes"]["predictive_analytics"]["historic_clv"]:
                historicClvs.append(person["attributes"]["predictive_analytics"]["historic_clv"]) 
    
    # Iterate through all pages from get profiles endpoint, appending CLVs from each page to the historicClvs variable
    pages_remaining = True


    while(pages_remaining):
        getPageCLV(response)
        url = response.json()["links"]["next"]
        response = requests.get(url, headers=headers)
        if not response.json()["links"]["next"]:
            pages_remaining = False


    # calculate threshold for top X% of customers
    threshold = np.percentile(historicClvs,100-userPercentile)


    # print the CLV threshold
    response = requests.post(url, json=payload, headers=headers)
    print(response.text)

Note that depending on the size of your dataset, it may take several minutes to execute this program. 

Impact

Using this script, you can easily identify the threshold that separates your top n% of customers from the rest of your base of contacts. Consider offering your most loyal customers: 

• Early access or sneak peeks to new product launches
• The opportunity to provide feedback on new releases 
• Invites to exclusive events
• Coupon codes or special offers to show your appreciation

By providing VIP treatment to your most loyal customers, you can help ensure their commitment to your brand for years to come.