---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# Lists and Pagination

List routes return your company's items, newest first, in pages.

## Pagination

| Parameter | Default | What it does |
| --- | --- | --- |
| `page` | `1` | The page, starting at 1 |
| `limit` | `10` | Items per page, from 1 to 100 |
| `sort` | `created_at` | The field to sort by |
| `direction` | `desc` | `asc` or `desc` |

The response contains the items in `data`, the page URLs in `links` and the totals in `meta`:

```json
{
  "data": [{ "id": 315968, "name": "Maria Silva" }],
  "links": {
    "first": "https://payments.cefis.com.br/api/v1/customers?page=1",
    "last": "https://payments.cefis.com.br/api/v1/customers?page=4",
    "prev": null,
    "next": "https://payments.cefis.com.br/api/v1/customers?page=2"
  },
  "meta": { "current_page": 1, "last_page": 4, "per_page": 10, "total": 37 }
}
```

To read everything, increase `page` up to `meta.last_page`.

> 📘 Plans
>
> `GET /plans` only paginates when you send `page` or `limit`. Without either, it returns all plans at once, without `links` and `meta`.

## Filters

Filters that accept a list are repeated in the query string: `status[]=active&status[]=overdue`. Date ranges (`YYYY-MM-DD`) only apply when both the start **and** the end are sent.

### `GET /customers`

| Filter | What it does |
| --- | --- |
| `query` | Searches the name, email, CPF or CNPJ |
| `status[]` | `1` (active) or `2` (inactive) |

### `GET /subscriptions`

| Filter | What it does |
| --- | --- |
| `customer_id` | A customer's subscriptions |
| `plan_id` | A plan's subscriptions |
| `status[]` | `new`, `trial`, `active`, `overdue`, `paused`, `canceled` or `expired` |
| `query` | Searches the customer's name, email, CPF or CNPJ, the plan name and the `custom_data` values |
| `created_at_start` and `created_at_end` | Created within the range |
| `end_at_start` and `end_at_end` | Ending within the range |

It also accepts `sort=customer_name`, to sort by customer name.

### `GET /payments`

| Filter | What it does |
| --- | --- |
| `subscription_id` | A subscription's invoices |
| `payment_link_id` | The payments of a payment link |
| `show_only_individual` | `true`: only one-off charges (no subscription, link or payment booklet) |
| `method[]` | `credit`, `debit`, `pix` or `billet` |
| `status[]` | `unpaid`, `paid`, `unauthorized`, `canceled` or `reversed` |
| `query` | Searches the customer's name, email, CPF or CNPJ, the amount and the card digits |
| `created_at_start` and `created_at_end` | Created within the range |
| `due_date_start` and `due_date_end` | Due within the range |
| `paid_at_start` and `paid_at_end` | Paid within the range |

Card validations and the start of trial periods do not appear in the payments list.