---
title: "Customer value report"
method: GET
path: "/reports/customer-value"
tags: ["Reports"]
---

# Customer value report

`GET /reports/customer-value`

Generates a customer value report with flexible grouping and metric calculations.

## Query parameters

- `groupBy` string, required
- `granularity` string
- `secondaryGroupBy` string
- `secondaryGranularity` string
- `measures` string
- `withTotal` boolean
- `createdAt` object
  - `eq` string, date-time
  - `ne` string, date-time
  - `gt` string, date-time
  - `gte` string, date-time
  - `lt` string, date-time
  - `lte` string, date-time
  - `in` string[]
  - `nin` string[]
  - `contains` string, date-time
- `displayStatus` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `currency` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `amount` object
  - `eq` number
  - `ne` number
  - `gt` number
  - `gte` number
  - `lt` number
  - `lte` number
  - `in` number[]
  - `nin` number[]
  - `contains` number
- `gatewayProfile` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `paymentMethod` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `paymentMethod.type` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `product` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `price` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `customer.billingAddress.country` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `customer.shippingAddress.country` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmSource` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmMedium` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmCampaign` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmTerm` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmContent` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmId` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string
- `attribution.utmContentid` object
  - `eq` string
  - `ne` string
  - `like` string
  - `in` string[]
  - `nin` string[]
  - `contains` string

## Response `200`

OK

- CustomerValueReportResponseDTO
  - `data` object[], required — Report data rows grouped by the specified field
    - `groupBy` string, nullable — The value of the groupBy field (field name varies based on groupBy parameter)
    - `secondaryGroupBy` string, nullable — The value of the secondaryGroupBy field (present only when secondaryGroupBy was supplied)
    - `fcQuantity` number — Number of first-charge conversions
    - `fcAmount` number — Total first-charge amount (in display currency)
    - `fcAov` number — Average order value for first-charge payments (in display currency)
    - `upsellsQuantity` number — Number of upsell transactions
    - `upsellsItemsCount` number — Total number of line items across upsell transactions. May exceed `upsellsQuantity` when upsells contain multiple line items.
    - `upsellsAmount` number — Total upsell amount (in display currency)
    - `upsellsAov` number — Average order value for upsell transactions (in display currency)
    - `totalAov` number — Overall average order value including first-charges and upsells (in display currency)
    - `rebillsQuantity` number — Number of rebill transactions
    - `rebillsItemsCount` number — Total number of line items across rebill transactions. May exceed `rebillsQuantity` when rebills contain multiple line items.
    - `rebillsAmount` number — Total rebill amount (in display currency)
    - `ltv` number — Customer lifetime value (in display currency)
  - `total` object — Aggregated totals across all groups (only present when withTotal is enabled)
    - `groupBy` string, nullable — The value of the groupBy field (field name varies based on groupBy parameter)
    - `secondaryGroupBy` string, nullable — The value of the secondaryGroupBy field (present only when secondaryGroupBy was supplied)
    - `fcQuantity` number — Number of first-charge conversions
    - `fcAmount` number — Total first-charge amount (in display currency)
    - `fcAov` number — Average order value for first-charge payments (in display currency)
    - `upsellsQuantity` number — Number of upsell transactions
    - `upsellsItemsCount` number — Total number of line items across upsell transactions. May exceed `upsellsQuantity` when upsells contain multiple line items.
    - `upsellsAmount` number — Total upsell amount (in display currency)
    - `upsellsAov` number — Average order value for upsell transactions (in display currency)
    - `totalAov` number — Overall average order value including first-charges and upsells (in display currency)
    - `rebillsQuantity` number — Number of rebill transactions
    - `rebillsItemsCount` number — Total number of line items across rebill transactions. May exceed `rebillsQuantity` when rebills contain multiple line items.
    - `rebillsAmount` number — Total rebill amount (in display currency)
    - `ltv` number — Customer lifetime value (in display currency)

## Other responses

- `202` — The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.
- `400` — The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it; or `payment_error` when the payment was refused by the issuer or processor.
- `401` — No API key was supplied, or the key is not valid. `type` is `authentication_error`.
- `403` — The API key is valid but lacks the permission this operation requires. `type` is `permission_error`.
- `429` — Too many requests. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.
- `500` — The request could not be completed because of an unexpected error. `type` is `api_error`.
- `504` — The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.

---

[API](https://skmtc.dev/odus/apis/odus-orchestration-api.md) · [All operations](https://skmtc.dev/odus/apis/odus-orchestration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/odus/odus-orchestration-api/revisions/d5fdcba31576/schema)