Sorting and filtering

Sorting

When you retrieve or filter resources through our APIs, you can return sorted data. Data can be sorted by one or more attributes. The sorting direction can be either ascending (default) or descending for each of the supported attributes.

Supported endpoints and attributes

Resource	Endpoint(s)	Sortable attributes
Bills	List bills	`created_at` `finalized_at` `id` `paid_at` `status` `updated_at`
Customers	List customers	`email` `id`
Invoices	List invoices	`created_at` `id` `status`
Organizations	List organizations	`created_at` `customers_count` `id` `name`
Plans	List plans	`id` `nickname`
SKUs	List SKUs	`id` `name` `product_id`
Vendors	List vendors	`created_at` `email` `first_name` `id` `last_name`

Examples

To retrieve all customers sorted in an ascending order by their email addresses, you can use the following URL:

GET https://www.pelcro.com/api/v1/core/customers?sort=email

To retrieve all customers sorted in an descending order by their email addresses, you can use the following URL:

GET https://www.pelcro.com/api/v1/core/customers?sort=-email

Filtering

When requesting a list of resources through our APIs, you can search and get only the results you want by adding special filters to the query parameters using the following format:

GET https://www.pelcro.com/api/v1/core/customers?filter[ATTRIBUTE]=(OPERATOR):?VALUE

In the above url :

ATTRIBUTE can be any attribute detailed in the sections below,
OPERATOR is an allowed operator for this ATTRIBUTE,
VALUE is the value you would like to search for

Searching works by adding filters for supported attributes for the given resource endpoint, and by specifying an operator with a value to use. Adding an operator is optional; if not specified, it always defaults to the eq operator.

Supported endpoints and attributes

Resource	Endpoint(s)	Filterable attributes
Bills	List bills	`created_at` `finalized_at` `id` `number` `paid_at` `period_end` `period_start` `status` `total` `updated_at` `user_id`
Customers	List customers	`email` `first_name` `id` `last_name` `metadata.*` `phone`
Invoices	List invoices	`id` `metadata.*` `status` `user_id`
Memberships	List memberships	`subscription_id` `user_id`
Organizations	List organizations	`id` `name`
Plans	List plans	`id` `nickname`
SKUs	List SKUs	`id` `name` `product_id`
Sources	List sources	`user_id`
Subscriptions	List subscriptions	`user_id`
Vendors	List vendors	`email` `first_name` `id` `last_name` `phone`

Supported operators

Operator	Description
eq	Performs an exact search, effectively returning only results exactly matching `VALUE`
oreq	Same as `eq`, but condition combining the filters will be `OR` instead of `AND`
like	Performs a fuzzy search, effectively returning any results containing `VALUE`
orlike	Same as `like`, but condition combining the filters will be `OR` instead of `AND`
has	Determines if a top-level attribute exists in the `metadata`
orhas	Same as `has`, but condition combining the filters will be `OR` instead of `AND`. Accepts a single key only — a comma-separated list is rejected

Examples

To retrieve all customers having articles in metadata as a top-level attribute, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[metadata]=has:articles

To retrieve all customers having a top-level metadata attribute of old_id equal to 22288, this is the filter you would use:

GET https://www.pelcro.com/api/v1/core/customers?filter[metadata.old_id]=eq:22288

To retrieve all customers having first names containing the string Audra, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[first_name]=like:Audra

To retrieve all customers having emails containing either John OR mysite.com, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[email]=like:John,mysite.com

Filtering on dates

The date attributes are created_at, updated_at, period_start, period_end, finalized_at and paid_at.

With eq or oreq, the value has to be one the column can be compared against:

Value	Example
A date	`2026-01-01`
A date and time	`2026-01-01 09:30:00`
An ISO 8601 timestamp	`2026-01-01T09:30:00+00:00`
A Unix timestamp, in seconds or milliseconds	`1767259800`

A Unix timestamp is read as UTC. Any other value — a year on its own, such as eq:2026 — is rejected with 400 Bad Request.

With like or orlike the stored timestamp is compared as text, so a partial value is meaningful and is the way to filter a month or a year:

GET https://www.pelcro.com/api/v1/core/bills?filter[created_at]=like:2026-08

Combining filters

Of course, you can combine as many filters as you want on different attributes. Let's take a look at some examples:

Note that the combination of primary filters in the above example is effectively doing a series of AND requests. This means that if any of the filters using those operators narrows the result down to nothing, the response is empty, regardless of whether other filters do match valid results.

On List customers and List SKUs, an empty result is returned as a 404 Not Found with no response body. Every other list endpoint returns 200 OK with an empty data array.

For more flexibility during searching, you can add OR operators to your filters.

As an example, if you want to fetch all customers having a first name containing either Jane orJohn, OR having a last name containing the string Doe, OR having an email on Gmail:

GET https://www.pelcro.com/api/v1/core/customers?filter[first_name]=like:Jane,John&filter[last_name]=orlike:Doe&filter[email]=orlike:gmail.com

Expected behaviors and limitations

Please note that the following are currently in effect when using the filter query parameter:

All searches are case-insensitive
When no operator is specified on any given filter, the default is always eq
Filters must contain at least one primary operator. Primary operators are eq, like and has
The has or orhas operators can only by used against metadata, only on top level-attributes
For metadata search, like and orlike operators are not supported
Multiple filters for the same attribute cannot be detected, hence is not supported
When combining an or operator with any other primary operators, filters are independent of one another, meaning you will get the results of both filters