Data Aggregations

Payiano's API provides powerful data aggregation capabilities that enable analytical-style queries for dashboards, reports, and business intelligence. The aggregation system allows you to compute metrics, group data by dimensions, and generate summary statistics from your resource collections.

Tip: Aggregations are applied to list endpoints through the aggregations query parameter and require response_type=json_aggregate to return analytical results.

Aggregation Structure

The aggregation system uses a structured JSON format that defines both the metrics to compute and the dimensions to group by. This enables flexible analytical queries that can answer complex business questions.

Metrics

Calculations

Define the numerical calculations to perform on your data, such as sums, averages, and counts. Metrics are computed across the aggregated dataset.

Dimensions

Grouping

Specify how to segment and categorize your data for analysis. Grouping enables breakdowns by categories, dates, statuses, or other meaningful dimensions.

enum AggregationFieldMetrics { 'avg' = 'avg', 'count' = 'count', 'sum' = 'sum' } type AggregationFieldMetric = keyof typeof AggregationFieldMetrics
interface IAggregationField { field: string metrics: AggregationFieldMetric[] }
interface IAggregationGroupBy { field: string }
interface IAggregation { fields: (IAggregationField)[] group_by?: (IAggregationGroupBy)[] }

Key Characteristics

Performance Optimized

Maximum 5 aggregation fields and 5 group by fields per request to maintain optimal query performance.

Type Safety

Metrics are validated against field types (e.g., avg/sum only on numeric fields) to prevent invalid queries.

Flexible Grouping

Group by multiple dimensions and customize datetime grouping with timezone support.

Analytical Focus

Designed specifically for reporting and dashboard use cases with optimized response formats.

Available Metrics

Metric	Description	Applicable Field Types	Example Output
`count`	Count of records in the group	boolean, date, datetime, enum, enum_number, ulid	`"count": 150`
`sum`	Sum of values in the group	numeric	`"sum": 12500.50`
`avg`	Average value in the group	numeric	`"avg": 83.34`

Grouping Behavior

Datetime Field Grouping

When grouping by datetime fields (created_at, updated_at, paid_at, etc.), the system automatically groups by the date portion only, ignoring the time component. This enables daily-based aggregations instead of precise timestamp-level grouping.

Example:

Records from 2024-01-15 10:30:00 and 2024-01-15 14:45:00 will be grouped together under 2024-01-15

Performance Limits

To maintain optimal performance and avoid overly complex queries, aggregation requests are limited to 5 group by fields and 5 aggregation fields per request.

Note: If a request includes more than 5 group by fields, the system will automatically limit the grouping to the first 5 valid fields to ensure optimal performance.

Timezone Handling

By default, grouping operations use the server's timezone (UTC). You can override this behavior by specifying the X-Preferred-Response-Timezone header in your request.

Learn more: See our Datetime & Timezone Reference for detailed timezone handling information.

Global Aggregation

If no group_by fields are provided, the system performs a global aggregation across the entire dataset. The response includes a single summary group, typically referencing the latest created_at value.

Practical Examples

Basic Aggregation

Calculate the total sum and average amount of payment links, grouped by currency code:

{
"fields": [
{ "field": "payment_details.amount",
"metrics": [ "sum", "avg" ] } ],
"group_by": [
{ "field": "payment_details.currency_code" } ] }

Multi-Dimensional Analysis

Analyze payment performance by status and creation date, calculating multiple metrics including total sum and average:

1curl "https://api.payiano.com/v1/payment/payment_links?aggregations[fields][0][field]=payment_details.amount&aggregations[fields][0][metrics][0]=sum&aggregations[fields][0][metrics][1]=avg&aggregations[fields][1][field]=payment_details.paid_amount&aggregations[fields][1][metrics][0]=sum&aggregations[fields][1][metrics][1]=avg&aggregations[group_by][0][field]=payment_details.status&aggregations[group_by][1][field]=created_at&response_type=json_aggregate" \ 2 -H "Authorization: Bearer ACCESS-TOKEN"

{
"fields": [
{ "field": "payment_details.amount",
"metrics": [ "sum", "avg" ] },
{ "field": "payment_details.paid_amount",
"metrics": [ "sum", "avg" ] } ],
"group_by": [
{ "field": "payment_details.status" },
{ "field": "created_at" } ] }

Global Summary

Get overall business metrics without grouping - a single summary of all payment links:

1curl "https://api.payiano.com/v1/payment/payment_links?aggregations[fields][0][field]=payment_details.amount&aggregations[fields][0][metrics][0]=sum&aggregations[fields][0][metrics][1]=avg&aggregations[fields][1][field]=payment_details.paid_amount&aggregations[fields][1][metrics][0]=sum&response_type=json_aggregate" \ 2 -H "Authorization: Bearer ACCESS-TOKEN"

{
"fields": [
{ "field": "payment_details.amount",
"metrics": [ "sum", "avg" ] },
{ "field": "payment_details.paid_amount",
"metrics": [ "sum" ] } ] }