Bills

Retrieve bills for linked biller accounts. Use an access token (from the token exchange) or IAM credentials to fetch bills for a specific account link.

Related guide: Retrieve Bills

The Bill object

Attributes

Field	Type	Description
id*	string	Unique bill identifier
biller_id*	string	Identifier of the biller that issued this bill
biller_name*	string	Display name of the biller
account_number*	string	The user's account number with the biller
amount*	number	Bill amount in the smallest currency unit (e.g., cents)
currency*	string	ISO 4217 currency code (e.g., "USD")
due_date*	string	ISO 8601 date when the bill is due
status*	string	Bill status: PENDING, PAID, or OVERDUE
statement_date*	string	ISO 8601 date when the statement was issued
description	string	Human-readable description of the bill
auto_pay_enabled	boolean	Whether auto-pay is enabled for this account
line_items	object[]	Itemized charges on the bill (see Line Item schema below)

Line Item

Field	Type	Description
description*	string	Description of the line item charge
amount*	number	Amount for this line item

Example Bill object

JSON

{
  "id": "bill_abc123",
  "biller_id": "test_electric_company",
  "biller_name": "Test Electric Company",
  "account_number": "****4567",
  "amount": 15420,
  "currency": "USD",
  "due_date": "2026-04-15",
  "status": "PENDING",
  "statement_date": "2026-03-28",
  "description": "April 2026 Electric Bill",
  "auto_pay_enabled": false,
  "line_items": [
    { "description": "Electric usage (820 kWh)", "amount": 13100 },
    { "description": "Distribution charge", "amount": 1520 },
    { "description": "State tax", "amount": 800 }
  ]
}

GET/bills/get

Get bills for an account link. Supports pagination via cursor and filtering by date range. Authenticate with either IAM credentials or a Bearer access token.

Query Parameters

Field	Type	Description
account_link_id*	string	The account link ID from the token exchange
start_date	string	Filter bills with due date on or after this ISO 8601 date
end_date	string	Filter bills with due date on or before this ISO 8601 date
limit	integer	Number of bills to return (default: 50)
cursor	string	Pagination cursor from a previous response

Response

{
  "bills": [Bill],
  "has_more": false,
  "next_cursor": null
}

# With IAM credentials
curl "https://sandbox.api.billerapi.com/bills/get?account_link_id=link_abc123&limit=10" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"

# With access token
curl "https://sandbox.api.billerapi.com/bills/get?account_link_id=link_abc123" \
  -H "Authorization: Bearer at_sandbox_xyz789"

GET/bills/:id

Retrieve a single bill by its ID. Authenticate with either IAM credentials or a Bearer access token.

Path Parameters

Field	Type	Description
id*	string	The bill ID

# With IAM credentials
curl https://sandbox.api.billerapi.com/bills/bill_abc123 \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"

# With access token
curl https://sandbox.api.billerapi.com/bills/bill_abc123 \
  -H "Authorization: Bearer at_sandbox_xyz789"