This is a staging build of the docs
We've reorganized our products to make building with Codat easier than ever
Skip to main content

Lifetime value

Reference document for the endpoint that produces lifetime value data

The Lifetime Value endpoint retrieves the value of a specific company over one or more periods of time.

Refer to the Lending reporting structure page for more detail on reports in Lending.

For Lifetime Value, these are the dimensions and measures:

Dimensions

  • Period
  • Lifetime value metrics: the average revenue that a customer will generate throughout their lifespan for the given period.

Measures

  • Value

Report Data

  • Is structured based on dimension (index =“0”), i.e. Period.
  • The endpoint will return metrics on lifetime value for each period.

View the Lifetime Value formulas.

The endpoint is available in our API reference.

GET /data/companies/{companyId}/connections/{connectionId}/lending/commerceMetrics/lifetimeValue

Parameters

ParameterTypeDescriptionRequired
reportDatestring
See Date
YYYY-MM-DD
Datetime or Date (inclusive of the whole day).
Required
periodUnitstringThe period unit of time returned, and it can be: “Day”, “Week”, “Month”, “Year”.Required
periodLengthintegerBased on the period unit provided. It must be positive, not zero and an integer.Required
numberOfPeriodsintegerThe number of periods to return. It must be positive, not zero and an integer.Required
includeDisplayNamesbooleanShows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.
Default is false.
Optional

Data model

The response structure is split into four areas: Report info, Dimensions, Measures and Report data.

Report info

FieldTypeDescription
namestring"lifetime_value"
displayNamestring"Lifetime Value"

Dimensions

Lifetime value consists of these dimensions: Period and Customer retention metrics.

Dimension (index = “0”): Period

FieldTypeDescription
displayNamestring"Period"
typestring"datespan"
itemsarray
See Dimension (index = “0”) items
Returns an array of “Period”. This is driven by the query parameter values.
Ordered by latest to earliest periods.

Dimension (index = “0”) items

FieldTypeDescription
displayNamestring"Period n"
startstring
See Date
YYYY-MM-DD, date in which the period begins (inclusive).
endstring
See Date
YYYY-MM-DD, date in which the period ends (inclusive).

Dimension (index = “1”): Lifetime value metrics

FieldTypeDescription
displayNamestring"Customer retention metrics"
typestring"string"
itemsarray
See Dimension (index = “1”) items
Returns an array of customer retention metrics.

Dimension (index = “1”) items

FieldTypeDescription
valuestring“Lifetime value”
This will always show for any response in this report. The dimension values are not dependent on the user’s query parameters.

Measures

Measures provide information about the measures contained in the report data.

The measure for this report is as follows:

Index “1” - Value

FieldTypeDescription
displayNamestring“Value”
unitsstringThe base currency of the company’s commerce connection.
typestring“currency”

Report data

The report data combines multiple reporting dimensions and outputs the value of each combination. Each dimension reference is specified.

Since the report data is reflective of two dimensions and their measures, the tables below represent each component grouping.

Each object is grouped by dimension (index=“0”) which is the number of periods specified by the user in the query parameters.

Each period will be broken down into Lifetime value metrics.

Components structure

FieldTypeDescription
dimensionnumberIndex 1
dimensionDisplayNamestringShows when includeDisplayNames is set to true.
itemstring
itemDisplayNamestringShows when includeDisplayNames is set to true.
measuresSee Measures in components

All components have the structure described in the Measures in components data model below.

Measures in components

Index “1” (value)

FieldTypeDescription
measureDisplayNamestring“Value"
valuestring

Example data

{
"reportInfo": {
"name": "lifetime_value",
"displayName": "Lifetime Value"
},
"dimensions": [
{
"index": 0,
"displayName": "Period",
"type": "datespan",
"items": [
{
"index": 0,
"displayName": "Period 0",
"start": "2021-08-30",
"end": "2021-09-30"
},
{
"index": 1,
"displayName": "Period 1",
"start": "2021-09-30",
"end": "2021-10-31"
}
]
},
{
"index": 1,
"displayName": "Lifetime value metrics",
"type": "string",
"items": [
{
"index": 0,
"value": "Lifetime value"
}
]
}
],
"measures": [
{
"displayName": "Value",
"units": "GBP",
"index": 0,
"type": "currency"
}
],
"reportData": [
{
"dimension": 0,
"dimensionDisplayName": "Period",
"item": 0,
"itemDisplayName": "Period 0",
"components": [
{
"dimension": 1,
"dimensionDisplayName": "Lifetime value metrics",
"item": 0,
"itemDisplayName": "Lifetime value",
"measures": [
{
"index": 0,
"measureDisplayName": "Value",
"value": 0.00
}
]
}
]
},
{
"dimension": 0,
"dimensionDisplayName": "Period",
"item": 1,
"itemDisplayName": "Period 1",
"components": [
{
"dimension": 1,
"dimensionDisplayName": "Lifetime value metrics",
"item": 0,
"itemDisplayName": "Lifetime value",
"measures": [
{
"index": 0,
"measureDisplayName": "Value",
"value": 0.00
}
]
}
]
}
]
}

Was this page useful?
❤️
👍
🤔
👎
😭