> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Filter Segments

> Save and reuse named filter presets on any list view. Filter segments let your team bookmark common search configurations so they don't have to rebuild filters from scratch on every visit.

## Overview

Filter segments store a named collection of filter predicates scoped to a specific page module and account. Any user on the account can save, browse, and apply segments — but only authenticated users (not API tokens) can manage them.

A segment captures the exact filter state — type, value ID, and display label — mirroring the frontend's `ActiveFilter` shape so segments can be hydrated directly into URL params without translation.

```json
{
  "id": "seg_dev_a1b2c3d4e5f6g7h8",
  "module": "subscriptions",
  "name": "Active trials — USD",
  "filters": [
    { "type": "status", "id": "trialing", "label": "Trialing" },
    { "type": "currency", "id": "usd", "label": "USD" }
  ],
  "created_by_user_id": "usr_dev_...",
  "created_at": "2024-06-01T10:00:00Z",
  "updated_at": "2024-06-01T10:00:00Z"
}
```

## Filter predicates

Each segment stores an array of filter predicates — the individual filters that make up the saved view.

| Field   | Type   | Constraints   | Description                                                            |
| ------- | ------ | ------------- | ---------------------------------------------------------------------- |
| `type`  | string | Max 64 chars  | Filter type key (e.g. `product`, `currency`)                           |
| `id`    | string | Max 255 chars | Filter value identifier — an option ID, date string, or numeric string |
| `label` | string | Max 255 chars | Display label for the filter chip and active-filter bar                |

The predicate shape mirrors the frontend's active filter format so segments can be hydrated directly into URL params without translation.

## Authentication

Filter segments require user authentication. Requests authenticated with API tokens receive a `403 Forbidden` response. This feature is designed for interactive dashboard use, not API integrations.

## Listing segments

Retrieve all segments for an account scoped to a module. Results are paginated and searchable by name.

```bash
GET /api/{account_id}/filter-segments/?module=subscriptions
```

**Query parameters:**

| Parameter    | Required | Description                                                    |
| ------------ | -------- | -------------------------------------------------------------- |
| `module`     | Yes      | The module key to filter by (e.g. `subscriptions`, `invoices`) |
| `page`       | No       | Page number (default: 1)                                       |
| `page_size`  | No       | Items per page                                                 |
| `search`     | No       | Search by segment name                                         |
| `sort_by`    | No       | Sort field: `created_at`, `updated_at`, or `name`              |
| `sort_order` | No       | `asc` or `desc`                                                |

See [List Filter Segments](/api-reference/api-reference/filter-segments/list-filter-segments) for the full API reference.

## Creating a segment

Save the current filter state as a named segment.

```bash
POST /api/{account_id}/filter-segments/
```

```json
{
  "module": "subscriptions",
  "name": "Active trials — USD",
  "filters": [
    { "type": "status", "id": "trialing", "label": "Trialing" },
    { "type": "currency", "id": "usd", "label": "USD" }
  ]
}
```

| Field     | Required | Constraints                 |
| --------- | -------- | --------------------------- |
| `module`  | Yes      | 1–64 characters             |
| `name`    | Yes      | 1–80 characters             |
| `filters` | Yes      | Array of predicates, max 50 |

See [Create Filter Segment](/api-reference/api-reference/filter-segments/create-filter-segment) for the full API reference.

## Retrieving a segment

Fetch a single segment by ID.

```bash
GET /api/{account_id}/filter-segments/{segment_id}
```

Returns a `404` if the segment does not exist or belongs to a different account.

See [Get Filter Segment](/api-reference/api-reference/filter-segments/get-filter-segment) for the full API reference.

## Updating a segment

Rename a segment, update its filters, or reassign it to a different module. All fields are optional — only the fields you provide are updated.

```bash
PATCH /api/{account_id}/filter-segments/{segment_id}
```

| Field     | Type   | Constraints         |
| --------- | ------ | ------------------- |
| `name`    | string | 1–80 characters     |
| `module`  | string | 1–64 characters     |
| `filters` | array  | Up to 50 predicates |

```json
{
  "name": "Active trials — EUR",
  "filters": [
    { "type": "status", "id": "trialing", "label": "Trialing" },
    { "type": "currency", "id": "eur", "label": "EUR" }
  ]
}
```

Returns a `400` if no fields are provided. Returns a `404` if the segment does not exist.

See [Update Filter Segment](/api-reference/api-reference/filter-segments/update-filter-segment) for the full API reference.

## Deleting a segment

Remove a segment permanently. Returns `204 No Content` on success.

```bash
DELETE /api/{account_id}/filter-segments/{segment_id}
```

Returns a `404` if the segment does not exist.

See [Delete Filter Segment](/api-reference/api-reference/filter-segments/delete-filter-segment) for the full API reference.

## Limits

| Limit                           | Value          | Notes             |
| ------------------------------- | -------------- | ----------------- |
| Filters per segment             | 50             |                   |
| Segment name length             | 80 characters  | Must be non-empty |
| Module key length               | 64 characters  | Must be non-empty |
| Filter predicate `type` length  | 64 characters  |                   |
| Filter predicate `id` length    | 255 characters |                   |
| Filter predicate `label` length | 255 characters |                   |