Visualizing Distributions

Let's explore a different use case: visualizing the distribution of customer purchase amounts across percentiles. This can help you understand the spending habits of your customers, identify the most valuable segments, and tailor your marketing or product offerings accordingly.

What you will build

You will log individual purchase amounts, query the value at every percentile, and chart the result. Unlike an average, this curve answers questions such as:

• What does a typical customer spend? Look near P50 (the median).
• Where do high-value customers begin? Compare P75, P90, and P95.
• How extreme is the long tail? Compare P99 with the median.

A percentile is a threshold, not a share of revenue. If P90 is $148, 90% of purchases are at or below $148 and 10% are above it.

Prerequisites

• A valid API key for Telemetry
• Basic understanding of JavaScript and Node.js
• An e-commerce platform or any system where customer purchases are tracked

1. Install the Telemetry SDK

First, you need to install the Telemetry SDK in your project. If you haven’t done so already, run the following command:

npm install telemetry-sh

2. Initialize Telemetry

After installing the SDK, import and initialize Telemetry in your project. Replace YOUR_API_KEY with your actual Telemetry API key.

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

3. Log purchase amounts

To visualize the distribution of customer purchase amounts, you need to log the amount each time a purchase is made. Here’s an example function to log this data:

const logPurchaseAmount = (customerId, purchaseAmount) => {
  telemetry.log("customer_purchases", {
    customer_id: customerId,        // The ID of the customer
    purchase_amount: purchaseAmount, // The purchase amount in dollars
    currency: "USD",
    status: "completed"
  });
};

// Example usage
logPurchaseAmount("customer_123", 49.99);  // Log a purchase amount for a customer
logPurchaseAmount("customer_456", 120.50); // Log another purchase amount for a different customer

4. Instrument completed purchases

You should set up your system to automatically log purchase amounts whenever a transaction is completed. This can be done by integrating the logging function into your checkout or payment processing system. Here’s a simplified example:

const processPurchase = (customerId, amount) => {
  // Additional logic for processing the purchase

  // Log the purchase amount
  logPurchaseAmount(customerId, amount);
};

// Example transactions
processPurchase("customer_123", 75.00);    // Log a purchase of $75
processPurchase("customer_789", 300.00);   // Log a purchase of $300

5. Query the distribution

Once you’ve logged sufficient data, you can use Telemetry’s UI to visualize the distribution of purchase amounts across percentiles.

1. Create a percentile query:

   • In the Telemetry UI, navigate to the query section.

   • Use the following SQL-like query to generate percentile data:

     WITH purchases AS (
       SELECT purchase_amount
       FROM customer_purchases
       WHERE timestamp_utc >= now() - INTERVAL '90 days'
         AND currency = 'USD'
         AND status = 'completed'
     )
     SELECT 50 AS percentile,
       approx_percentile_cont(purchase_amount, 0.50) AS purchase_amount
     FROM purchases
     UNION ALL
     SELECT 75, approx_percentile_cont(purchase_amount, 0.75)
     FROM purchases
     UNION ALL
     SELECT 90, approx_percentile_cont(purchase_amount, 0.90)
     FROM purchases
     UNION ALL
     SELECT 95, approx_percentile_cont(purchase_amount, 0.95)
     FROM purchases
     UNION ALL
     SELECT 99, approx_percentile_cont(purchase_amount, 0.99)
     FROM purchases
     ORDER BY percentile;
     

   • This query generates a compact curve at the percentiles most teams use. Add more fixed percentile rows when a smoother curve materially changes the decision.

2. Visualize the data:
   • In the UI, create a line chart with percentile on the X-axis and purchase_amount on the Y-axis.
   • This will give you a distribution curve showing how purchase amounts vary across different customer percentiles, helping you identify the spending patterns within your customer base.

Interpret the curve

Start with P50 to understand the typical purchase, then compare it with P90 and P99. A sharp rise near the right edge indicates a small high-spend segment; a flatter curve indicates spending is more evenly distributed. Before acting on the result, filter refunds and test transactions, keep currency units consistent, and compare the same time window across segments.