---
updatedAt: 2026-07-29T12:01:36.000Z
---

Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.

# Balance configuration filter templates

This guide provides step-by-step guidance how to create and manage filter templates and use them in balance configurations.  It also explains how to maintain and update filter logic efficiently.

When [creating a balance configuration](https://developers.pismo.io/pismo-docs/reference/post-v1-balances-config), you can specify filters in the `filters` field or you can refer to a predefined filter template in the `filter_template_id` field. When the Pismo platform processes a transaction, it reads the `filter_template_id`, retrieves the associated template, and applies filters exactly as if they were inline.

# When to use filter templates

Use filter templates with balance configurations when:

* It makes sense to reuse the same filter logic across multiple configurations
* You want to set up centralized control over filtering rules
* You expect frequent updates to filter logic

# Validation rules

When [creating a balance configuration](https://developers.pismo.io/pismo-docs/reference/post-v1-balances-config), the following are valid balance configurations.

* When only `filter_template_id` is provided.
* When only `filters` are provided (legacy mode).

The following invalid balance configurations return errors.

| Scenario                                            | Error           |
| :-------------------------------------------------- | :-------------- |
| Both `filter_template_id` and `filters` provided    | 400 Bad Request |
| Neither `filter_template_id` and `filters` provided | 400 Bad Request |
| Template not found                                  | 404 Not Found   |

# Create filter template

Use the [Create filter template](https://developers.pismo.io/pismo-docs/reference/post-v1-filter-templates)  endpoint to create a reusable filter definition.

In the following request payload example, a new filter template called `transport` defines a processing code (PC), a number of minimum and maximum installments, two Merchant Category Codes (MCCs), and a currency code.

```json
{
  "id": "transport",
  "description": "Transportation-related transactions",
  "filters": {
    "processing_codes": [
      "01"
    ],
    "min_installments": 1,
    "max_installments": 12,
    "mcc": [
      "1234", 
      "5678"
    ],
    "currency_code": "USD"
  }
}
```

<Callout icon="📘" theme="info">
  Important considerations

  * The `id` value must be unique per organization and cannot exceed 36 characters.
  * The `description` value must be a maximum of 50 characters.
  * The `filters` must follow the existing balance configuration filter structure.
</Callout>

# Validate template creation

Use the [Get filter template](https://developers.pismo.io/pismo-docs/reference/get-v1-filter-template-by-id)  endpoint to retrieve the created template by its ID and verify the template was created successfully.

# Use template in balance configuration

Use the [Create balance configuration](https://developers.pismo.io/pismo-docs/reference/post-v1-balances-config)  endpoint to reference the template in the `filter_template_id` field.

```json
{
  "level": "account",
  "account_id": 999,
  "configs": [
    {
      "filter_template_id": "transport",
      "is_active": true,
      "scenarios": [
        {
          "condition": {
            "order": 1,
            "type": "default"
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "amount": "contract_amount"
          }
        }
      ]
    }
  ]
}
```

# Update filter template

Use the [Update filter template](https://developers.pismo.io/pismo-docs/reference/put-v1-filter-template)  endpoint to modify an existing template. The changes automatically apply to all balance configurations that use this template, so there's no need to update individual configurations.

The following request payload adds a new processing code (`02`) and a new MCC (`9999`) to the existing filter template (`transport`).

```json
{
  "description": "Transport-related transactions",
  "filters": {
    "processing_codes": [
      "01", 
      "02"
    ],
    "mcc": [
      "1234", 
      "5678", 
      "9999"
    ],
    "currency_code": "USD"
  }
}
```

# List templates

Use the [List all filter templates](https://developers.pismo.io/pismo-docs/reference/get-v1-filter-templates) endpoint to list every balance configuration template available to the organization and ensure reuse instead of duplication.

# Migrate inline filters to templates

1. Identify duplicated filter logic across balance configurations.
2. Create a filter template with that logic.
3. Replace inline filters with `filter_template_id`.
4. Validate configurations.

## Before (inline filters)

```json
{
  "filters": {
    "processing_codes": [
    "01"
    ],
    "min_installments": 1,
    "max_installments": 12,
    "mcc": [
    "1234", 
    "5678"
    ],
    "currency_code": "USD"
  }
}
```

## After (using template)

```json
{
  "filter_template_id": "transport"
}
```

# Best practices

## Reusability

Create filter templates for:

* PC lists
* MCC groups
* Currency-based filters
* Installment-based rules

## Naming conventions

Use descriptive filter template IDs. For example:

* `transport_domestic`
* `ecommerce_usd`
* `installments_1_12`

## Governance

* Avoid duplicate templates
* Review existing templates before creating new ones

## Change management

Treat template updates carefully as changes impact all linked balance configurations.