Contents
Overview
The enhanced GET APIs support advanced querying capabilities through aggregation and filtering parameters, enabling developers to retrieve report-ready data directly from API responses.
These capabilities include:
- Filtering records using conditions
- Grouping results by specific fields
- Performing aggregation functions such as sum and count
This functionality eliminates the need for additional data processing and aligns closely with UI-supported filtering behavior.
Prerequisites
Before using aggregation capabilities, ensure that Aggregation Filtering is enabled in CSP settings.
Contact the Ordway Support Team to request enablement.
Important
- Group By and Aggregate By will not function unless this setting is enabled.
- Filter By functionality is available independently but must still follow UI and metadata constraints
Supported Modules
Aggregation is supported for the following modules:
| Customer | Product | Webhooks | Subscription |
| Currencies | Billing Schedule | Revenue Schedule | Plan |
| Refunds | Product Tax Group | Revenue Rules | Order |
| Billing Runs | Payments | Debit Memos | Price Book |
| Credits | Quotes | Invoice | Usages |
Important
Aggregation support is module specific. Each module supports only its respective UI fields.
Filter By
Filters records based on field-level conditions.
Applicability
- Supported for all UI-supported fields
- Controlled via metadata (condition = true)
Constraints
- Field must exist in UI
- Field must support filtering in metadata
Example Method – Filter By
Request
| GET /api/v1/customers?filter_by=status:eq:active |
Behavior
Unsupported fields may:
- Return no results (or)
- return an error
Invalid Example
| GET/api/v1/customers?filter_by=names:eq:Amarnath |
Response
|
{ "error": "Invalid params: Invalid filter field: names for module: customer" } |
Important: If a field is not available in the UI, the API may return empty results or an error.
Group By
Groups records based on selected fields.
Applicability
- Supported only on parent (main) fields
Limitations
- Child or associated fields are not supported
Example Method – Group By
Request
|
GET /api/v1/customers?group_by=id GET /api/v1/customers?group_by=status&page=3 |
Response
|
{ "data": [ { "status": "active" }, { "status": "inactive" } ], "total_records": 2, "size": 20, "page": 3, "errors": [] } |
Invalid Example
Request
| GET/api/v1/customers?group_by=contact.display_name |
Response
|
{ "error": "Invalid params: group_by does not support joined table fields: contact.display_name. Only main module (customer) fields are allowed" } |
Aggregate By
Performs calculations on dataset results.
Supported Functions
- SUM
- COUNT
Example Method – Aggregate By
Request
| GET /api/v1/customers?aggregate_by=sum:balance,count:id&size=51 |
Response
|
{ "data": [ { "balance_SUM": -781161.413356781, "id_COUNT": 146 } ], "total_records": 146, "size": 50, "page": 1, "errors": [] } |
Combined Example (Filter, Group, and Aggregate Example)
Request
| /api/v1/customers?filter_by=status:eq:active&group_by=status&aggregate_by=count:id |
Response
|
{ "data": [ { "status": "active", "id_COUNT": 20 } ], "total_records": 1, "size": 20, "page": 1, "errors": [] } |
Supported Operators
- eq — equals
- gt — greater than
- lt — less than
- gte — greater than or equal to
- lte — less than or equal to
Note: Existing operators such as =, <, and > continue to be supported for backward compatibility.
Pagination and Response Metadata
API responses include pagination and metadata fields:
- total_records — Total number of records returned
- size — Number of records per page
- page — Current page number
- errors — Any errors encountered
These fields ensure efficient handling of large datasets.
Key Considerations
Important
- Aggregation is supported only on list endpoints
- Only UI-supported fields can be used
- Group By does not support child or associated fields
- Aggregation requires CSP enablement
- API behavior must align with UI filtering capabilities
Error Handling
| Scenario | Behavior |
| Invalid filter field | Error / empty response |
| Invalid group field | Error |
| Aggregation disabled | Group/Aggregate fails |
| UI mismatch | Invalid results |
Refer to the API Documentation: https://ordwaylabs.stoplight.io/docs/ordway/cc92aacfd225c-list-customers
Comments
0 comments
Please sign in to leave a comment.