> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill pay rules API

> Create and manage routing rules programmatically using the bill pay API.

This guide covers the bill pay rules API — creating rules, understanding the condition AST structure, configuring actions, and managing rule lifecycle.

## Endpoints

| Method   | Endpoint                                         | Purpose                |
| -------- | ------------------------------------------------ | ---------------------- |
| `GET`    | `/api/v2/company/{id}/bill-pay/rules/`           | List all rules         |
| `POST`   | `/api/v2/company/{id}/bill-pay/rules/`           | Create a rule          |
| `GET`    | `/api/v2/company/{id}/bill-pay/rules/{id}/`      | Get rule detail        |
| `PATCH`  | `/api/v2/company/{id}/bill-pay/rules/{id}/`      | Update a rule          |
| `DELETE` | `/api/v2/company/{id}/bill-pay/rules/{id}/`      | Delete a rule          |
| `GET`    | `/api/v2/company/{id}/bill-pay/destinations/`    | List destinations      |
| `POST`   | `/api/v2/company/{id}/bill-pay/destinations/`    | Create a destination   |
| `GET`    | `/api/v2/company/{id}/bill-pay/decisions/`       | List routing decisions |
| `GET`    | `/api/v2/company/{id}/bill-pay/cycles/`          | List bill pay cycles   |
| `GET`    | `/api/v2/company/{id}/bill-pay/funding-summary/` | Funding overview       |

## Rule structure

A rule consists of:

* **`name`** — human-readable label
* **`description`** — optional explanation of the rule's purpose
* **`phase`** — either `ROUTING` or `GL_CODING`
* **`isActive`** — whether the rule is currently being evaluated
* **`priority`** — evaluation order (lower numbers evaluate first)
* **`conditionAst`** — the condition tree (see below)
* **`actions`** — array of action objects

## Condition AST

Conditions are expressed as an abstract syntax tree (AST) with four node types:

### COMPARE node

Tests a single field against a value:

```json theme={null}
{
  "type": "COMPARE",
  "field": "bill.totalCharges",
  "operator": "GT",
  "value": "5000"
}
```

### AND node

All children must match:

```json theme={null}
{
  "type": "AND",
  "children": [
    { "type": "COMPARE", "field": "bill.datasourceType", "operator": "EQ", "value": "ELECTRICITY" },
    { "type": "COMPARE", "field": "bill.totalCharges", "operator": "GT", "value": "1000" }
  ]
}
```

### OR node

Any child can match:

```json theme={null}
{
  "type": "OR",
  "children": [
    { "type": "COMPARE", "field": "site.id", "operator": "EQ", "value": "uuid-1" },
    { "type": "COMPARE", "field": "site.id", "operator": "EQ", "value": "uuid-2" }
  ]
}
```

### NOT node

Inverts the child:

```json theme={null}
{
  "type": "NOT",
  "child": { "type": "COMPARE", "field": "bill.isFlagged", "operator": "EQ", "value": "true" }
}
```

## Condition fields

| Field                 | Value type     | Description                                                      |
| --------------------- | -------------- | ---------------------------------------------------------------- |
| `bill.datasourceType` | string (enum)  | Commodity: ELECTRICITY, GAS, WATER, WASTE, FUEL, SOLAR, DISTRICT |
| `bill.totalCharges`   | decimal        | Total bill amount                                                |
| `bill.isFlagged`      | boolean        | Whether the bill is flagged                                      |
| `bill.datasource`     | UUID           | Specific utility provider                                        |
| `bill.chargesUnits`   | string         | Currency code (USD, CAD, EUR, etc.)                              |
| `site.id`             | UUID           | Specific site                                                    |
| `site.tags`           | string (multi) | Site tags                                                        |
| `site.location`       | string (multi) | Site location                                                    |
| `account.id`          | UUID           | Specific account                                                 |
| `workflow.id`         | UUID           | Specific connection                                              |

## Operators

| Operator       | Applies to    | Description                               |
| -------------- | ------------- | ----------------------------------------- |
| `EQ`           | All           | Equals                                    |
| `NEQ`          | All           | Does not equal                            |
| `IN`           | Enum, UUID    | Is one of (array value)                   |
| `NOT_IN`       | Enum, UUID    | Is not one of (array value)               |
| `CONTAINS`     | String        | Contains substring                        |
| `NOT_CONTAINS` | String        | Does not contain substring                |
| `GT`           | Decimal, Date | Greater than                              |
| `GTE`          | Decimal, Date | Greater than or equal                     |
| `LT`           | Decimal, Date | Less than                                 |
| `LTE`          | Decimal, Date | Less than or equal                        |
| `BETWEEN`      | Decimal, Date | Between two values (array of \[min, max]) |
| `IS_NULL`      | All           | Field is empty (no value argument)        |
| `IS_NOT_NULL`  | All           | Field has a value (no value argument)     |

## Action types

### Routing rule actions

<CodeGroup>
  ```json Forward to email theme={null}
  {
    "type": "FORWARD_EMAIL",
    "destinationId": "uuid-of-email-destination"
  }
  ```

  ```json Route to AP integration theme={null}
  {
    "type": "ROUTE_TO_AP_INTEGRATION",
    "destinationId": "uuid-of-erp-destination"
  }
  ```

  ```json Request funds (centralized payment) theme={null}
  {
    "type": "REQUEST_FUNDS"
  }
  ```

  ```json Notify user theme={null}
  {
    "type": "NOTIFY_USER",
    "userIds": ["uuid-1", "uuid-2"]
  }
  ```
</CodeGroup>

### GL coding rule actions

```json theme={null}
{
  "type": "ASSIGN_GL_CODE",
  "glCode": "6200",
  "glCodeName": "Utilities - Water"
}
```

## Creating a rule (example)

```bash theme={null}
curl -X POST \
  https://api.nectarclimate.com/api/v2/company/{company_id}/bill-pay/rules/ \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Forward large electricity bills to CFO",
    "description": "Bills over $10k need CFO review before AP processes them",
    "phase": "ROUTING",
    "isActive": true,
    "conditionAst": {
      "type": "AND",
      "children": [
        {
          "type": "COMPARE",
          "field": "bill.datasourceType",
          "operator": "EQ",
          "value": "ELECTRICITY"
        },
        {
          "type": "COMPARE",
          "field": "bill.totalCharges",
          "operator": "GT",
          "value": "10000"
        }
      ]
    },
    "actions": [
      {
        "type": "FORWARD_EMAIL",
        "destinationId": "uuid-of-cfo-destination"
      }
    ]
  }'
```

## Rule evaluation behavior

* Rules are evaluated in **priority order** (lower number = higher priority)
* **All matching rules fire** — evaluation doesn't stop at the first match
* Actions are **deduplicated by destination** — if two rules route to the same destination, delivery happens only once
* GL coding rules evaluate before routing rules in the same pass
* A rule with **no conditions** matches every bill (acts as a catch-all)

## Decisions (evaluation results)

After evaluation, each bill gets a decision record accessible via the decisions endpoint. The decision includes:

* Which rules were evaluated
* Which rules matched (with full condition trace)
* What actions fired and their delivery status (`PENDING`, `APPLIED`, `DELIVERED`, `FAILED`)

## Related pages

* [Bill pay lifecycle](/developer-guide/bill-pay-lifecycle) — cycle statuses and state transitions
* [API versions](/developer-guide/api-versions) — versioning and authentication
* [Bill Pay Rules (platform guide)](/platform/bill-pay/rules) — end-user documentation