All list requests can be paginated and filtered using the same query format. For convenience, we’ve made sure all list-based endpoints returned data with the same structure.


We’re using 2 parameters for pagination:

  • take is the number of items the API will return, default is 50, max is 100
  • skip is the number of items the API will skip, default is 0

So if you want to get the first 50 items of a list, you don’t need any parameters. If you need items from the 350th to the 425th, you’ll use take=75 and skip=350.

Here’s an example with the customer list:

curl --request GET \
  --url '' \
  --header 'Authorization: Bearer <token>'

The API will always return a similarly shaped payload containing:

  • data the items you requested
  • meta the contextual information (total number of items, number selected…)

For instance for customers:

  "meta": {
    "total": 2,
    "taken": 2,
    "skipped": 0
  "data": [
      "id": "cus_3fhwCWcL0Rx5MQ"
      // other properties
      "id": "cus_9huL9ahn7KQqHo"
      // other properties


Our API is offering many filtering capabilities so you can always find what you’re looking for. Filters are passed as query parameters using a common pattern.


For instance:

  • GET /v1/customers?name__contains=instagram will return all customers with the name containing instagram
  • GET /v1/customers?id__in=123,456,789 will return customers with ID equals to 123, 456, or 789

List of available operators

  • equals (or just <field>=xxx)
  • not
  • lt
  • lte
  • gt
  • gte
  • contains
  • startsWith
  • endWith
  • in
  • notIn
  • isNull
  • isNotNull

Numerical operators can be applied to numbers or dates.

Not all fields can be filtered, please refer to each model in the API Reference to see which ones are available.