Pagination and Filtering
All group API resources have support for bulk fetches via List API resources and filtering by query params. The sections that follow explain how you can use the Pagination and Filtering.
Pagination
You can list subscriptions, list customers, and list invoices. These list API methods share a common structure
Pagination can be controlled by page_size parameter that limits the number of resources to be returned in the response. The value ranges from 1 to 100 and defaults to 20.
List API methods returns an object with these four attributes:
count: The total existing objects.
next: The query path to go to next results.
previous: The query path to go to previous results.
results: The list with the results objects.
Filtering
In the List API resources, filtering of resources can be performed using query parameters. Please refer to the corresponding resource's documentation for the complete list of supported query parameters. The following types of query parameters are supported now:
string
enumerated string
number
date
datetime
boolean
The operators supported for a query parameter is based on the query parameter type, as explained below:
Filter operators:
Operator | Supported type | Example |
gt Returns the objects, if the filter attribute's value is greater than the specified value. | number | &amount__gt=1000 |
gte Returns the objects, if the filter attribute's value is greater than or equal to the specified value. | number | &amount__gte=1000 |
lt Returns the objects, if the filter attribute's value is lesser than the specified value. | number | &amount__lt=1000 |
lte Returns the objects, if the filter attribute's value is lesser than or equal to the specified value. | number | &amount__lte=1000 |
range Takes in two values as input. Returns the objects, if the filter attribute's value falls within the specified range. | number date datetime | &amount__between=1000,2000 |
in Returns the objects, if the filter attribute's value matches any one of the specified values. | all types | &status__in=active,archived |
contains Returns the objects, if the filter attribute's value contains specified value respecting capital letters. | string | &name__contains=Acme |
icontains Returns the objects, if the filter attribute's value contains specified value. | string | &name__icontains=acme |
exact Returns the objects, if the filter attribute's value is exact to specified value respecting capital letters. | string | &address__exact=St |
iexact Returns the objects, if the filter attribute's value is exact to specified value. | string | &address__iexact=street |
year Returns the objects, if the filter attribute's value is exact to specified year value. | date datetime | &created__year=2019 |
day Returns the objects, if the filter attribute's value is exact to specified day value. | date datetime | &created__day=01 |
month Returns the objects, if the filter attribute's value is exact to specified month value. | date datetime | &created__month=06 |
isnull Returns the objects, if the filter attribute's value is null or no, specified True or False value. | all types | &email__isnull=True |
startswith Returns the objects, if the filter attribute's value starts with the specified value. | string | &email__startswith=aaron |
endswith Returns the objects, if the filter attribute's value ends with the specified value. | string | &email__endswith=gmail.com |
Nested filtering
Filter on nested objects is supported. Use an expression like these for filter by nested objects:
/invoices/?customer__name__endswith=llc Returns all invoices objects that customer name ends with LLC.
/subscriptions/?lines__plan__name__icontains=basic Returns all subscriptions objects that plan name contain basic.
In the same way you can make use of filter operators on nested objects.
Last updated