Sorting and filtering

Sorting and filtering capabilities enables you to build complex queries in order to find exactly what you are looking for.

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

Endpoint	Attributes
List customers	`id` `email`
List invoices	`id` `status` `created_at`
List organizations	`id` `name` `created_at`
List skus	`id` `name` `product_id`
List subscriptions	`status`

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

Endpoint	Attributes
List customers	`email` `first_name` `last_name` `metadata.*`
List invoices	`id` `status` `metadata.*`
List members	`user_id` `subscription_id`
List organizations	`name`
List skus	`id` `name` `product_id`
List sources	`user_id`

Supported operators

Operator	Description	Usage
eq	Performs an exact search, effectively returning only results exactly matching `VALUE`	`filtereters]` `filter{` `filter "h-0": =eq:VALUE1,VALUE2`
oreq	Same as `eq`, but condition combining the filters will be `OR` instead of `AND`	`filtereters]` `filter{`
like	Performs a fuzzy search, effectively returning any results containing `VALUE`	`filtereters]` `filter{`
orlike	Same as `like`, but condition combining the filters will be `OR` instead of `AND`	`filtereters]` `filter{`
has	Determines if a top-level attribute exists in the `metadata`	`filtereters]`
orhas	Same as `has`, but condition combining the filters will be `OR` instead of `AND`	`filtereters]`

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

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 return an empty result, you will receive a 404 Not Found HTTP status code, regardless of whether other filters do match valid results. 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