5 min read

GET /revenue/:websiteId/ltv

Retrieve customer lifetime value (LTV) analysis by cohort. Groups customers by their first purchase date and tracks cumulative revenue per customer over subsequent time periods, enabling you to understand long-term customer value trends.

GET/api/external/v1/revenue/:websiteId/ltv

Get LTV cohort analysis

Authentication

All requests require an API key passed via the X-API-Key header. Alternatively, you can use the Authorization: Bearer YOUR_API_KEY header.

AuthenticationBash

curl -X GET 'https://api.zenovay.com/api/external/v1/revenue/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ltv?range=90d&granularity=monthly' \
-H 'X-API-Key: YOUR_API_KEY'

This endpoint requires a Pro plan or higher. Free-tier API keys will receive a 403 Forbidden response.

LTV analysis requires revenue tracking to be configured for your website. If no revenue data is available, the response will contain empty cohorts.

Credit Cost

Each request to this endpoint costs 1 API credit.

Parameters

Name	Type	Required	Default	Description
`websiteId`	string (path)	Yes	-	The UUID of the website
`range`	string (query)	No	`90d`	Time range: `24h`, `7d`, `30d`, `90d`
`granularity`	string (query)	No	`monthly`	Cohort granularity: `weekly`, `monthly`

Response

Response (200 OK)JSON

{
"success": true,
"data": {
  "cohorts": [
    {
      "cohort_date": "2026-01-01",
      "customers": 245,
      "periods": [
        {
          "period": 0,
          "cumulative_revenue_per_customer": 48.50
        },
        {
          "period": 1,
          "cumulative_revenue_per_customer": 72.30
        },
        {
          "period": 2,
          "cumulative_revenue_per_customer": 89.15
        }
      ]
    },
    {
      "cohort_date": "2026-02-01",
      "customers": 312,
      "periods": [
        {
          "period": 0,
          "cumulative_revenue_per_customer": 52.10
        },
        {
          "period": 1,
          "cumulative_revenue_per_customer": 78.90
        }
      ]
    },
    {
      "cohort_date": "2026-03-01",
      "customers": 289,
      "periods": [
        {
          "period": 0,
          "cumulative_revenue_per_customer": 55.20
        }
      ]
    }
  ],
  "summary": {
    "average_ltv_30d": 52.60,
    "average_ltv_90d": 89.15
  }
},
"timestamp": "2026-03-16T15:00:00.000Z"
}

Response Fields

Field	Type	Description
`cohorts`	array	List of LTV cohort records
`cohorts[].cohort_date`	string	First purchase date of the cohort (YYYY-MM-DD)
`cohorts[].customers`	number	Number of customers in the cohort
`cohorts[].periods`	array	Revenue data for each subsequent period
`cohorts[].periods[].period`	number	Period number (0 = first purchase period, 1 = next period, etc.)
`cohorts[].periods[].cumulative_revenue_per_customer`	number	Cumulative revenue per customer up to this period (in account currency)
`summary.average_ltv_30d`	number	Average customer LTV at 30 days across all cohorts
`summary.average_ltv_90d`	number	Average customer LTV at 90 days across all cohorts

Understanding LTV Cohorts

Each cohort represents customers grouped by when they made their first purchase. The periods array shows how cumulative revenue per customer grows over time:

Cohort	Period 0	Period 1	Period 2
Jan 2026	$48.50	$72.30	$89.15
Feb 2026	$52.10	$78.90	-
Mar 2026	$55.20	-	-

Period 0 represents the initial purchase. Each subsequent period adds revenue from repeat purchases, giving you a clear view of how customer value compounds over time.

TypeScript Interface

LTVResponseTypeScript

interface LTVPeriod {
period: number;
cumulative_revenue_per_customer: number;
}

interface LTVCohort {
cohort_date: string;
customers: number;
periods: LTVPeriod[];
}

interface LTVResponse {
success: true;
data: {
  cohorts: LTVCohort[];
  summary: {
    average_ltv_30d: number;
    average_ltv_90d: number;
  };
};
timestamp: string;
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Pro plan or higher required
404	Not Found - Website not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Code Examples

cURLBash

curl -X GET 'https://api.zenovay.com/api/external/v1/revenue/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ltv?range=90d&granularity=monthly' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

Error Handling

Error Response (403 Forbidden)JSON

{
"success": false,
"error": {
  "message": "This endpoint requires a Pro plan or higher",
  "code": "PLAN_REQUIRED",
  "timestamp": "2026-03-16T15:00:00.000Z"
}
}