# Customer value report `GET /v2/reports/customer-value` Core API v2, Reports. Generates a customer value report with flexible grouping and metric calculations. **Authentication:** Send `Authorization: Bearer `. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer ` ## Parameters ### Query parameters - `groupBy` (string, required): Field to group results by. **Available fields:** `createdAt`, `currency`, `product.name`, `price.name`, `attribution.utmSource`, `attribution.utmCampaign` Example: `createdAt`. - `granularity` (string): Date granularity for `groupBy` when it is a date field. Defaults to `day`. `hour` additionally requires the query to be bounded to a `createdAt` range of at most two days. Accepts `hour`, `day`, `week`, `month`, `quarter`, `year`; anything else falls back to the default. - `secondaryGroupBy` (string): Optional second axis for pivoting (must differ from groupBy). Each row will then carry both the primary `groupBy` value and a `secondaryGroupBy` value. **Available fields:** `createdAt`, `currency`, `product.name`, `price.name`, `attribution.utmSource`, `attribution.utmCampaign` - `secondaryGranularity` (string): Date granularity for `secondaryGroupBy` when it is a date field. Defaults to `day`. - `measures` (string): Metrics to include in the results. Multiple measures can be specified as comma-separated values. If `measures` is not provided, all metrics specified in the config will be calculated. **Available metrics:** `fcQuantity`, `fcAmount`, `fcAov`, `upsellsQuantity`, `upsellsItemsCount`, `upsellsAmount`, `upsellsAov`, `totalAov`, `rebillsQuantity`, `rebillsItemsCount`, `rebillsAmount`, `ltv` Example: `fcQuantity,fcAmount,fcAov,upsellsQuantity,upsellsItemsCount,upsellsAmount,upsellsAov,totalAov,rebillsQuantity,rebillsItemsCount,rebillsAmount,ltv`. - `withTotal` (boolean): Whether to include a rollup row aggregating every group. Pass `false` to omit it. Default `true`. - `createdAt` (filter): Send as `createdAt[]=`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `displayStatus` (filter): Send as `displayStatus[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `currency` (filter): Send as `currency[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `amount` (filter): Send as `amount[]=`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `gatewayProfile` (filter): Send as `gatewayProfile[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `paymentMethod` (filter): Send as `paymentMethod[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `paymentMethod.type` (filter): Send as `paymentMethod.type[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `product` (filter): Send as `product[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `price` (filter): Send as `price[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `customer.billingAddress.country` (filter): Send as `customer.billingAddress.country[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `customer.shippingAddress.country` (filter): Send as `customer.shippingAddress.country[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmSource` (filter): Send as `attribution.utmSource[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmMedium` (filter): Send as `attribution.utmMedium[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmCampaign` (filter): Send as `attribution.utmCampaign[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmTerm` (filter): Send as `attribution.utmTerm[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmContent` (filter): Send as `attribution.utmContent[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmId` (filter): Send as `attribution.utmId[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. - `attribution.utmContentid` (filter): Send as `attribution.utmContentid[]=`. Operators: `eq`, `ne`, `like`, `ilike`, `in`, `nin`. ## Responses ### `200` OK Type: object (CustomerValueReportResponseDTO). - `data` (array of object, required): Report data rows grouped by the specified field. - `groupBy` (string, required, nullable): The value of the groupBy field (field name varies based on groupBy parameter) Example: `USD`. - `secondaryGroupBy` (string, nullable): The value of the secondaryGroupBy field (present only when secondaryGroupBy was supplied) Example: `eur`. - `fcQuantity` (number): Number of first-charge conversions. Example: `150`. - `fcAmount` (number): Total first-charge amount (in display currency) Example: `30000`. - `fcAov` (number): Average order value for first-charge payments (in display currency) Example: `200`. - `upsellsQuantity` (number): Number of upsell transactions. Example: `45`. - `upsellsItemsCount` (number): Total number of line items across upsell transactions. May exceed `upsellsQuantity` when upsells contain multiple line items. Example: `72`. - `upsellsAmount` (number): Total upsell amount (in display currency) Example: `9000`. - `upsellsAov` (number): Average order value for upsell transactions (in display currency) Example: `200`. - `totalAov` (number): Overall average order value including first-charges and upsells (in display currency) Example: `260`. - `rebillsQuantity` (number): Number of rebill transactions. Example: `300`. - `rebillsItemsCount` (number): Total number of line items across rebill transactions. May exceed `rebillsQuantity` when rebills contain multiple line items. Example: `480`. - `rebillsAmount` (number): Total rebill amount (in display currency) Example: `60000`. - `ltv` (number): Customer lifetime value (in display currency) Example: `660`. - `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) Example: `USD`. - `secondaryGroupBy` (string, nullable): The value of the secondaryGroupBy field (present only when secondaryGroupBy was supplied) Example: `eur`. - `fcQuantity` (number): Number of first-charge conversions. Example: `150`. - `fcAmount` (number): Total first-charge amount (in display currency) Example: `30000`. - `fcAov` (number): Average order value for first-charge payments (in display currency) Example: `200`. - `upsellsQuantity` (number): Number of upsell transactions. Example: `45`. - `upsellsItemsCount` (number): Total number of line items across upsell transactions. May exceed `upsellsQuantity` when upsells contain multiple line items. Example: `72`. - `upsellsAmount` (number): Total upsell amount (in display currency) Example: `9000`. - `upsellsAov` (number): Average order value for upsell transactions (in display currency) Example: `200`. - `totalAov` (number): Overall average order value including first-charges and upsells (in display currency) Example: `260`. - `rebillsQuantity` (number): Number of rebill transactions. Example: `300`. - `rebillsItemsCount` (number): Total number of line items across rebill transactions. May exceed `rebillsQuantity` when rebills contain multiple line items. Example: `480`. - `rebillsAmount` (number): Total rebill amount (in display currency) Example: `60000`. - `ltv` (number): Customer lifetime value (in display currency) Example: `660`. ### `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. Type: object (ProvisioningInProgress). - `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`. - `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`. ### Errors - `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; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it. - `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. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry. - `500`: The request could not be completed because of an unexpected error. `type` is `api_error`. - `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff. - `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. Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md). --- Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/reporting-controller-get-customer-value-report