Customer retention
Reference document for the endpoint that produces customer retention data
The Customer Retention endpoint retrieves customer information for a specific company's commerce connection, over one or more periods of time.
Refer to the Lending reporting structure page for more detail on reports in Lending.
For Customer Retention, these are the dimensions and measures:
Dimensions
- Period
- Customer retention metrics
This contains the following items:- Existing customers: the number of unique customers where they have placed an order(s) in the specified period AND any previous period.
- New customers: the number of unique customers where they have placed an order(s) in the specified period AND NONE in any previous period.
- Total customers: the sum of existing and new customers within the period.
- Retention rate: the percentage of existing customers within the period compared to the total customers at the end of the previous period.
- Repeat rate: the percentage of existing customers to total customers over the specified period.
Measures
- Count
- Percentage
Report Data
- Is structured based on dimension (index =“0”), i.e. Period.
- The endpoint will return metrics on existing customers, new customers**, total customers, retention rate and repeat rate** for each period.
View the Customer Retention formulas.
The endpoint is available in our API reference.
GET /data/companies/{companyId}/connections/{connectionId}/lending/commerceMetrics/customerRetention
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| reportDate | string See Date | YYYY-MM-DD Datetime or Date (inclusive of the whole day). | Required |
| periodUnit | string | The period unit of time returned, and it can be: “Day”, “Week”, “Month”, “Year”. | Required |
| periodLength | integer | Based on the period unit provided. It must be positive, not zero and an integer. | Required |
| numberOfPeriods | integer | The number of periods to return. It must be positive, not zero and an integer. | Required |
| includeDisplayNames | boolean | Shows 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
| Field | Type | Description |
|---|---|---|
| name | string | "customer_retention" |
| displayName | string | "Customer Retention" |
Dimensions
Customer retention consists of these dimensions: Period and Customer retention metrics.
Dimension (index = “0”): Period
| Field | Type | Description |
|---|---|---|
| displayName | string | "Period" |
| type | string | "datespan" |
| items | array 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
| Field | Type | Description |
|---|---|---|
| displayName | string | "Period n" |
| start | string See Date | YYYY-MM-DD Date in which the period begins (inclusive). |
| end | string See Date | YYYY-MM-DD Date in which the period ends (inclusive). |
Dimension (index = “1”): Customer retention metrics
| Field | Type | Description |
|---|---|---|
| displayName | string | "Customer retention metrics" |
| type | string | "string" |
| items | array See Dimension (index = “1”) items | Returns an array of customer retention metrics. |
Dimension (index = “1”) items
| Field | Type | Description |
|---|---|---|
| value | string | “Existing customers”, “New customers”, "Total customers", "Retention rate", or "Repeat rate". These 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 two measures for this report are as follows:
Index “0” - Count
| Field | Type | Description |
|---|---|---|
| displayName | string | "Count" |
| units | string | |
| type | number | "int" |
Index “1” - Percentage
| Field | Type | Description |
|---|---|---|
| displayName | string | “percentage” |
| units | string | |
| type | string | “percentage” |
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 Customer retention metrics.
Components structure
| Field | Type | Description |
|---|---|---|
| Field | Type | Description |
| dimension | number | Index 1 |
| dimensionDisplayName | string | Shows when includeDisplayNames is set to true. |
| item | number | |
| itemDisplayName | string | Shows when includeDisplayNames is set to true. |
| measures | See Measures in components |
All components have the structure described in the Measures in components data model below.
Measures in components
Index "0" (count)
| Field | Type | Description |
|---|---|---|
| measureDisplayName | string | "Count" |
| value | number |
Index “1” (value)
| Field | Type | Description |
|---|---|---|
| measureDisplayName | string | "value" |
| value | number |
Example data
{
"reportInfo": {
"name": "customer_retention",
"displayName": "Customer Retention"
},
"dimensions": [
{
"index": 0,
"displayName": "Period",
"type": "datespan",
"items": [
{
"index": 0,
"displayName": "Period 0",
"start": "2021-03-30",
"end": "2021-04-30"
},
{
"index": 1,
"displayName": "Period 1",
"start": "2021-04-30",
"end": "2021-05-31"
}
]
},
{
"index": 1,
"displayName": "Customer retention metrics",
"type": "string",
"items": [
{
"index": 0,
"value": "Existing customers"
},
{
"index": 1,
"value": "New customers"
},
{
"index": 2,
"value": "Total customers"
},
{
"index": 3,
"value": "Retention rate"
},
{
"index": 4,
"value": "Repeat rate"
}
]
}
],
"measures": [
{
"displayName": "Count",
"units": "",
"index": 0,
"type": "int"
},
{
"displayName": "Percentage",
"units": "",
"index": 1,
"type": "percentage"
}
],
"reportData": [
{
"dimension": 0,
"dimensionDisplayName": "Period",
"item": 0,
"itemDisplayName": "Period 0",
"components": [
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 0,
"itemDisplayName": "Existing customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 0
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 1,
"itemDisplayName": "New customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 7
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 2,
"itemDisplayName": "Total customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 7
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 3,
"itemDisplayName": "Retention rate",
"measures": [
{
"index": 1,
"measureDisplayName": "Percentage",
"value": 0.00
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 4,
"itemDisplayName": "Repeat rate",
"measures": [
{
"index": 1,
"measureDisplayName": "Percentage",
"value": 0.00
}
]
}
]
},
{
"dimension": 0,
"dimensionDisplayName": "Period",
"item": 1,
"itemDisplayName": "Period 1",
"components": [
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 0,
"itemDisplayName": "Existing customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 1
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 1,
"itemDisplayName": "New customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 8
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 2,
"itemDisplayName": "Total customers",
"measures": [
{
"index": 0,
"measureDisplayName": "Count",
"value": 9
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 3,
"itemDisplayName": "Retention rate",
"measures": [
{
"index": 1,
"measureDisplayName": "Percentage",
"value": 0.00
}
]
},
{
"dimension": 1,
"dimensionDisplayName": "Customer retention metrics",
"item": 4,
"itemDisplayName": "Repeat rate",
"measures": [
{
"index": 1,
"measureDisplayName": "Percentage",
"value": 11.11
}
]
}
]
}
]
}
Was this page useful?
❤️
👍
🤔
👎
😭