Bill pay rules 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:

{
  "type": "COMPARE",
  "field": "bill.totalCharges",
  "operator": "GT",
  "value": "5000"
}

AND node

All children must match:

{
  "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:

{
  "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:

{
  "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

{
  "type": "FORWARD_EMAIL",
  "destinationId": "uuid-of-email-destination"
}

{
  "type": "ROUTE_TO_AP_INTEGRATION",
  "destinationId": "uuid-of-erp-destination"
}

{
  "type": "REQUEST_FUNDS"
}

{
  "type": "NOTIFY_USER",
  "userIds": ["uuid-1", "uuid-2"]
}

GL coding rule actions

{
  "type": "ASSIGN_GL_CODE",
  "glCode": "6200",
  "glCodeName": "Utilities - Water"
}

Creating a rule (example)

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)

Bill pay lifecycle — cycle statuses and state transitions
API versions — versioning and authentication
Bill Pay Rules (platform guide) — end-user documentation

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Endpoints

Rule structure

Condition AST

COMPARE node

AND node

OR node

NOT node

Condition fields

Operators

Action types

Routing rule actions

GL coding rule actions

Creating a rule (example)

Rule evaluation behavior

Decisions (evaluation results)

​Endpoints

​Rule structure

​Condition AST

​COMPARE node

​AND node

​OR node

​NOT node

​Condition fields

​Operators

​Action types

​Routing rule actions

​GL coding rule actions

​Creating a rule (example)

​Rule evaluation behavior

​Decisions (evaluation results)

​Related pages

Endpoints

Rule structure

Condition AST

COMPARE node

AND node

OR node

NOT node

Condition fields

Operators

Action types

Routing rule actions

GL coding rule actions

Creating a rule (example)

Rule evaluation behavior

Decisions (evaluation results)

Related pages