Bills

Retrieve bills for linked biller accounts. List bills with your server API key and an account_link_id; single-bill detail also accepts the link-scoped access token returned by exchange. Subscribe to the bill.created and bill.updated webhook events to react to changes in real time.

Related guides: Retrieve Bills · ISO Bill Data Migration

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
total_amountobject	Canonical ISO 20022 amount when the legacy record can be enriched: decimal-string value plus ISO 4217 currency
due_date_isostring	Canonical ISO calendar date (YYYY-MM-DD)
amount*number	Deprecated legacy major-unit amount; use total_amount.value
currency*string	Deprecated legacy currency; use total_amount.currency
due_date*string	Deprecated legacy due date; use due_date_iso
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. New integrations should read total_amount and due_date_iso; the legacy fields remain during the release-relative deprecation window documented in the ISO bill-data migration guide.

The Bill object

{
  "id": "bill_abc123",
  "account_link_id": "link_abc123",
  "merchant_name": "Sandbox Utility",
  "total_amount": { "value": "154.20", "currency": "USD" },
  "due_date_iso": "2026-04-15",
  "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": "sb_utility"
}

GET/v1/bills

Get bills for an account link. Supports pagination via cursor and filtering by date range. Authenticate this list operation with your server API key. The required account_link_id scopes the result to one connected link.

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: 100, max: 500)
cursorstring	Pagination cursor from a previous response

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

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

Response

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

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

Response200 OK

{
  "id": "bill_abc123",
  "account_link_id": "link_abc123",
  "merchant_name": "Sandbox Utility",
  "total_amount": { "value": "154.20", "currency": "USD" },
  "due_date_iso": "2026-04-15",
  "amount": 154.20,
  "currency": "USD",
  "due_date": "2026-04-15",
  "status": "PENDING"
}

Was this page helpful?