logo

Retrieve a retention value report

The retention value report shows the count of new customers. per aggregation bucket and the corresponding per customer value over time.

SecuritySecretApiKey or JWT
Request
query Parameters
aggregationField
required
string

Report aggregation field.

Enum: "day" "month" "quarter" "year" "leadsSource" "leadsMedium" "leadsCampaign" "leadsContent" "leadsTerm" "leadsAffiliate" … 2 more
aggregationPeriod
required
string

Report aggregation period.

Enum: "day" "month" "quarter" "year"
periodStart
required
string <date>

Report start date.

periodEnd
required
string <date>

Report end date.

includeRefunds
string

If to include refunds.

Enum: "true" "false"
includeDisputes
string

If to include disputes.

Enum: "true" "false"
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

criteria
string

Criteria parameter for requesting a collection.

Responses
200

Report was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Example: 332
Pagination-Limit
integer

Items per page limit.

Example: 100
Pagination-Offset
integer

Pagination offset.

Example: 2
Response Schema: application/json
Array of objects
Array
aggregationValue
string

Value by which the report provides retention periods and values. The date values are displayed as following: Day: YYYY-MM-DD; Month: YYYY-MM; Quarter: YYYY-MM/YYYY-MM; Year: YYYY.

customersCount
integer

Number of customers within the aggregation with their first payment.

Array of objects
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/reports/retention-value
Request samples
const params = {
    aggregationField: 'month',
    aggregationPeriod: 'month',
    periodStart: '2016-09-01T00:00:00Z',
    periodEnd: '2017-09-01T00:00:00Z',
    includeRefunds: true,
    includeDisputes: false,
    limit: 20,
    offset: 0,
    tz: 0
};
const report = await api.reports.getRetentionValue(params);
Response samples
application/json
{
  • "data": [
    ]
}
➔ Next to Retrieve a revenue waterfall report