API Reference

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

OperatorSupported typeExample
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/?customernameendswith=llc Returns all invoices objects that customer name ends with LLC.
  • /subscriptions/?linesplanname__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.