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. Subscribe to the bill.created and bill.updated webhook events to react to changes in real time.

Related guide: Retrieve Bills

The Bill object

A Bill represents a single statement retrieved from a linked biller account — the amount owed, when it's due, and where the source document lives. Bills are created automatically when BillerAPI syncs a linked account and update in place as their status changes.

Attributes

id*string	Unique bill identifier
account_link_id*string	The account link this bill belongs to
merchant_name*string	Display name of the merchant / biller that issued this bill
amount*number	Bill amount in major currency units (dollars, not cents) — e.g. 154.20
currency*string	ISO 4217 currency code (e.g., "USD")
due_date*string	ISO 8601 date when the bill is due
status*string	Bill status: DRAFT, PENDING, PAID, PARTIALLY_PAID, or OVERDUE
categorystring	Bill category (e.g. "utilities")
descriptionstring	Human-readable description of the bill
document_urlstring	URL to the source bill document (PDF), when available
biller_idstring	Identifier of the biller that issued this bill

Itemized charges (line items) are not part of the Bill object. They live on the bill's statement — fetch GET /v1/bills/:id/statement to retrieve the full balance breakdown and line items.

The Bill object

{
  "id": "bill_abc123",
  "account_link_id": "link_abc123",
  "merchant_name": "Test Electric Company",
  "amount": 154.20,
  "currency": "USD",
  "due_date": "2026-04-15",
  "status": "PENDING",
  "category": "utilities",
  "description": "April 2026 Electric Bill",
  "document_url": "https://files.billerapi.com/bills/bill_abc123.pdf",
  "biller_id": "test_electric_company"
}

GET/v1/bills

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

account_link_id*string	The account link ID from the token exchange
start_datestring	Filter bills with due date on or after this ISO 8601 date
end_datestring	Filter bills with due date on or before this ISO 8601 date
limitinteger	Number of bills to return (default: 50)
cursorstring	Pagination cursor from a previous response

Sample uses your_client_id · sign in to auto-fill your sandbox key

# With IAM credentials
curl "https://sandbox.api.billerapi.com/v1/bills?account_link_id=link_abc123&limit=10" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

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

Response

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

GET/v1/bills/{id}

Retrieve a single bill by its ID. Authenticate with either IAM credentials or a Bearer access token. Returns a Bill object if a valid identifier was provided, and returns an error otherwise.

Path parameters

id*string

The bill ID

Sample uses your_client_id · sign in to auto-fill your sandbox key

# With IAM credentials
curl https://sandbox.api.billerapi.com/v1/bills/bill_abc123 \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

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

Response200 OK

{
  "id": "bill_abc123",
  "account_link_id": "link_abc123",
  "merchant_name": "Test Electric Company",
  "amount": 154.20,
  "currency": "USD",
  "due_date": "2026-04-15",
  "status": "PENDING"
}

Was this page helpful?