Advanced Filtering
Payiano's API provides a powerful and flexible filtering system that allows you to precisely query your data using structured conditions. The filtering capability supports complex logical operations, multiple field types, and nested conditions to meet your specific data retrieval needs.
filters query parameter and follow a consistent JSON structure across all Payiano APIs. Filter Structure
Payiano's filtering system uses a hierarchical JSON structure that supports complex logical operations. The system is built around two fundamental node types that can be nested to create sophisticated query conditions.
Group Nodes
ContainerLogical containers that combine multiple conditions or other groups using AND/OR operators. Groups can be nested to build complex filtering logic.
Condition Nodes
LeafIndividual filtering rules that specify field comparisons. Each condition defines what data to match using fields, operators, and values.
Key Characteristics
Hierarchical Structure
Groups can contain other groups, enabling complex nested logic with unlimited depth.
Type Safety
Operators are validated against field types to prevent invalid queries.
Flexible Logic
Mix AND/OR operators across different nesting levels for precise control.
API Consistency
Same structure works across all Payiano resources - payments, customers, checkouts, etc.
Available Operators
| Operator | Description | Applicable Types | Example |
|---|---|---|---|
eq | Equal to | boolean, date, enum, enum_number, number, reference_id, datetime, ulid, id | field = value |
not_eq | Not equal to | boolean, date, enum, enum_number, number, reference_id, datetime, ulid, id | field != value |
gt | Greater than | date, enum_number, number, datetime | field > value |
gte | Greater than or equal | date, enum_number, number, datetime | field >= value |
lt | Less than | date, enum_number, number, datetime | field < value |
lte | Less than or equal | date, enum_number, number, datetime | field <= value |
starts_with | Starts with | string | field LIKE "value%" |
not_starts_with | Does not start with | string | field NOT LIKE "value%" |
ends_with | Ends with | string | field LIKE "%value" |
not_ends_with | Does not end with | string | field NOT LIKE "%value" |
contains | Contains substring | string | field LIKE "%value%" |
not_contains | Does not contain substring | string | field NOT LIKE "%value%" |
in | In list of values | enum, enum_number, reference_id, ulid, id | field IN (value1, value2) |
not_in | Not in list of values | enum, enum_number, reference_id, ulid, id | field NOT IN (value1, value2) |
between | Between two values (inclusive) | date, enum_number, number, datetime | field BETWEEN value1 AND value2 |
not_between | Not between two values | date, enum_number, number, datetime | field NOT BETWEEN value1 AND value2 |
is_null | Is null | boolean, date, enum, enum_number, number, reference_id, string, datetime, ulid, id Only applicable to fields that can be null | field IS NULL |
is_not_null | Is not null | boolean, date, enum, enum_number, number, reference_id, string, datetime, ulid, id Only applicable to fields that can be null | field IS NOT NULL |
Practical Examples
Basic Filtering
Find payment links with amount greater than or equal to 2000 and status is paid:
Complex AND/OR Logical Groups
Find payment links that meet any of the following: have an amount greater than or equal to 2000, are either paid or pending, or are assigned to a customer, and were created between January 1, 2024, and December 31, 2024.