# BillRun REST API

BillRun exposes three families of HTTP endpoints:

- `/billapi/{collection}/{action}` - the modern entity API (CRUD + lifecycle
  actions on accounts, subscribers, plans, services, rates, balances, bills,
  discounts, charges, taxes, users, reports, etc).
- `/api/{action}` - the legacy action API used for one-off operations such as
  credit, payment, refunds, reports, subscribers lookup, and admin tasks.
- `/realtime` - the realtime rating/charging endpoint used by network
  elements (OCS-style start / update / release events).

Authentication is one of:

- Session cookie obtained via `POST /auth/login`.
- OAuth2 access token issued by `POST /oauth2/token`.
- Per-request signature using a shared secret (the `signature` parameter)
  for machine-to-machine integrations.

See [docs.bill.run](https://docs.bill.run/en/api/security) for the
authoritative behavior documentation; this OpenAPI document mirrors that
interface.


Open-source billing & rating platform - REST API reference.

Version: 6.0
License: AGPL-3.0

## Servers

Self-hosted BillRun instance
```
https://{host}
```

Variables:
- `host`: Hostname of your BillRun deployment
Default: "billing.example.com"

## Security

### sessionCookie

Obtained by calling `POST /auth/login` with a valid username/password
(or other configured protocol such as LDAP/SAML). The session cookie is
set automatically by the server and must be sent on every subsequent
request.


Type: apiKey
In: cookie
Name: PHPSESSID

### oauth2

OAuth2 client credentials grant. Issued by `POST /oauth2/token`.
Pass the returned access token in the `Authorization: Bearer <token>`
header on every subsequent request.


Type: oauth2

### secretSignature

HMAC-style signature computed from the request parameters and a
pre-shared secret (configured in BillRun under
`Settings -> Security -> Shared Secret`).

The same value can be passed in the request body for POST requests.
Validated by `Billrun_Utils_Security::validateData`. Used for
machine-to-machine integrations that do not maintain a session cookie
or OAuth2 token.


Type: apiKey
In: query
Name: signature

## Download OpenAPI description

[BillRun REST API](https://billrun.redocly.app/_bundle/openapi.bundled.yaml)

## Auth

Login, logout, available authentication protocols.

### Log in and obtain a session cookie

 - [POST /auth/login](https://billrun.redocly.app/openapi.bundled/auth/paths/~1auth~1login/post.md): Authenticate with one of the configured providers and receive a
PHPSESSID cookie. The cookie must be sent on subsequent requests.

The available providers are returned by GET /auth/options. The
protocol field selects which provider to use (defaults to
internal). For internal, the username/password pair is checked
against the BillRun users collection.

### Log out and destroy the session

 - [POST /auth/logout](https://billrun.redocly.app/openapi.bundled/auth/paths/~1auth~1logout/post.md): Terminates the session associated with the request cookie.

### List supported authentication protocols

 - [GET /auth/options](https://billrun.redocly.app/openapi.bundled/auth/paths/~1auth~1options/get.md): Returns the configured authentication providers, derived from
auth.protocols and auth. config keys. Use this to render
a "Sign in with..." picker.

## OAuth2

OAuth2 token endpoint.

### Issue an OAuth2 access token

 - [POST /oauth2/token](https://billrun.redocly.app/openapi.bundled/oauth2/paths/~1oauth2~1token/post.md): OAuth2 token endpoint. Supports the client_credentials,
password, and refresh_token grants depending on what the
BillRun OAuth2 server is configured for.

The returned access_token should be sent on subsequent calls as
Authorization: Bearer .

## BillAPI

Modern entity API at `/billapi/{collection}/{action}`. The same set of
actions (get, uniqueget, create, update, close, closeandnew, reopen,
delete, move, permanentchange, import, export) is applied to a range of
collections (accounts, subscribers, plans, services, rates, balances,
bills, charges, discounts, prepaidincludes, prepaidgroups, taxes,
reports, users, etc).


### Generic entity API

 - [POST /billapi/{collection}/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.generic.md): Generic shape of every BillAPI endpoint. See the per-collection paths
below for the parameter list applicable to a given collection/action
combination.

### Request shape

Parameters can be sent either as application/x-www-form-urlencoded
or application/json. The two most common are:

- query - a JSON-encoded MongoDB-style filter, used by read actions
  (get, uniqueget) and by mutating actions that target a specific
  revision (update, close, closeandnew, delete, ...).
- update - a JSON-encoded entity payload, used by all mutating
  actions.

### Response shape

All responses use the standard envelope - see
Envelope.

### Accounts collection

 - [POST /billapi/accounts/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.accounts.md): Customer accounts. Backed by the subscribers MongoDB collection
with type=account.

Supported actions: get, uniqueget, create, update, close,
closeandnew, reopen, delete, permanentchange, import.

### Subscribers collection

 - [POST /billapi/subscribers/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.subscribers.md): Subscribers belong to an account (linked by aid). Identified by
sid (auto-incremented).

Supported actions: get, uniqueget, create, update, close,
closeandnew, reopen, delete, move, permanentchange,
import.

### Plans collection

 - [POST /billapi/plans/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.plans.md): Billing plans (a.k.a. "rate plans"). Plans bundle recurring charges,
inclusive units, and rate overrides.

Supported actions: get, uniqueget, create, update, close,
closeandnew, reopen, delete, move, permanentchange.

### Services collection

 - [POST /billapi/services/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.services.md): Services are reusable bundles that can be attached to subscribers or
accounts (e.g. "VOIP Add-on", "Roaming Pack").

Supported actions: get, uniqueget, create, update, close,
closeandnew, reopen, delete, move, permanentchange.

### Rates / products collection

 - [POST /billapi/rates/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.rates.md): Rates (called "Products" in the UI) define how usage is priced.
Identified by key.

Supported actions: get, uniqueget, create, update, close,
closeandnew, reopen, delete, move, permanentchange.

### Balances collection

 - [POST /billapi/balances/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.balances.md): Monthly / cycle balance buckets per subscriber. Tracks inclusive
units consumed and over-usage charges.

Supported actions: get, uniqueget, update, delete.

### Bills collection

 - [POST /billapi/bills/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.bills.md): Bill documents - covers both invoices (type=inv) and payment
receipts/refunds (type=rec, type=ref).

Supported actions: get, uniqueget, update, delete.

### Charges collection

 - [POST /billapi/charges/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.charges.md): One-off or recurring charge definitions (e.g. activation fees,
late-payment fees).

### Discounts collection

 - [POST /billapi/discounts/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.discounts.md): Discount definitions. Can apply to plans, services, rates, or
arbitrary subscriber attributes.

### Prepaid includes (inclusive unit pools)

 - [POST /billapi/prepaidincludes/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.prepaidincludes.md): Definitions of inclusive-unit pools used by plans and services
(minutes, MB, SMS).

### Prepaid groups

 - [POST /billapi/prepaidgroups/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.prepaidgroups.md): Grouping of prepaid includes for shared consumption.

### Taxes collection

 - [POST /billapi/taxes/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.taxes.md): Tax rate definitions. Linked from plans, services and rates via the
tax array.

### Reports collection (definitions)

 - [POST /billapi/reports/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.reports.md): CRUD on saved report definitions. To run a report, see
POST /api/report.

### Users collection (admin/operator users)

 - [POST /billapi/users/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.users.md): Operator user accounts used to log in to BillRun. Subscribers (end
customers) live in the subscribers collection - see
/billapi/subscribers/.

### Lines (usage events / CDRs)

 - [POST /billapi/lines/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.lines.md): Raw usage records (a.k.a. "lines" or "CDRs"). Read-only via BillAPI;
mutating actions are normally driven by the calculator/aggregator
pipeline.

### Autorenew rules

 - [POST /billapi/autorenew/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.autorenew.md): Auto-renewal subscriptions that automatically re-charge a balance
or top-up at a defined interval.

### Health check

 - [GET /api](https://billrun.redocly.app/openapi.bundled/billapi/paths/~1api/get.md): Heartbeat. Verifies the DB is reachable.

### Reports collection (definitions)

 - [POST /billapi/reports/{action}](https://billrun.redocly.app/openapi.bundled/reports/billapi.reports.md): CRUD on saved report definitions. To run a report, see
POST /api/report.

## Reports

Run/list/export reports.

### Reports collection (definitions)

 - [POST /billapi/reports/{action}](https://billrun.redocly.app/openapi.bundled/billapi/billapi.reports.md): CRUD on saved report definitions. To run a report, see
POST /api/report.

### Reports collection (definitions)

 - [POST /billapi/reports/{action}](https://billrun.redocly.app/openapi.bundled/reports/billapi.reports.md): CRUD on saved report definitions. To run a report, see
POST /api/report.

### List report definitions

 - [GET /api/reports](https://billrun.redocly.app/openapi.bundled/reports/api.reports.list.md): Return the catalogue of saved report definitions visible to the
authenticated user.

### Run a report

 - [POST /api/report](https://billrun.redocly.app/openapi.bundled/reports/api.report.run.md): Execute a saved report (by key or _id) or an ad-hoc one passed
inline via the report field. Returns either the rendered rows
directly (small results) or a file URL for large ones.

## Credit

Credit lines (one-off charges or refunds).

### Credit a subscriber / account

 - [POST /api/credit](https://billrun.redocly.app/openapi.bundled/credit/api.credit.md): Create a credit line for a subscriber or account. Used both for
ad-hoc charges (positive aprice) and refunds (negative aprice).

The credit is recorded immediately as a lines record with
type=credit and goes into the next billing cycle (or the cycle
specified by billrun_key). For multi-installment credits, set
installments to a positive integer.

Implemented by Action_CreditAction::execute().

### Credit multiple subscribers in a single call

 - [POST /api/bulkcredit](https://billrun.redocly.app/openapi.bundled/credit/api.bulkcredit.md): Batch version of /api/credit. Accepts an array of credit requests
and processes each independently - one failure does not roll the
others back. The response status is 1 if all succeeded, 2 if
partial, 0 if all failed.

## Payment

Payments, bills, payment methods, adjustments.

### Pay / refund / deposit / split bill

 - [POST /api/pay](https://billrun.redocly.app/openapi.bundled/payment/api.pay.md): Multi-purpose payment endpoint. The action parameter selects the
sub-operation; when omitted, the call processes one or more
payments via the configured gateway.

Implemented by Action_PayAction::execute().

### Get / list bills (invoices, receipts, refunds)

 - [POST /api/bill](https://billrun.redocly.app/openapi.bundled/payment/api.bill.md): Fetch bills (invoices inv, payment receipts rec, refunds ref)
for one or more accounts. Supports pagination and filtering on
billing cycle, type, due date, and payment status.

Backed by Action_BillAction::execute(). For schema-validated
filtering, prefer /billapi/bills/get.

### Tokenize a payment card / start periodic payment

 - [POST /api/cards](https://billrun.redocly.app/openapi.bundled/payment/api.cards.md): Initiate a payment-card tokenization flow with the configured
payment gateway. Returns a redirect URL where the customer can
enter card details on a hosted page; on success BillRun receives a
tokenized identifier that can be used for subsequent recurring
charges.

### Adjust / reconcile payments

 - [POST /api/adjustpayments](https://billrun.redocly.app/openapi.bundled/payment/api.adjustpayments.md): Apply manual adjustments to outstanding payments (mark paid,
reject, deny, unconfirm). Implemented by
Action_AdjustPaymentAction.

### Generate a one-time invoice

 - [POST /api/onetimeinvoice](https://billrun.redocly.app/openapi.bundled/payment/api.onetimeinvoice.md): Generate an invoice for a list of charges outside of the regular
billing cycle. Returns the invoice document on success.

### List invoices for an account

 - [POST /api/accountinvoices](https://billrun.redocly.app/openapi.bundled/payment/api.accountinvoices.md): Return all invoices for one or more accounts, with optional
filtering by cycle / paid status. Backed by
Action_InvoicesAction.

## Realtime

Realtime charging events (start / update / release).

### Realtime charging event

 - [POST /realtime](https://billrun.redocly.app/openapi.bundled/realtime/realtime.event.md): Realtime event endpoint used by network elements (PGW, MMSC, SBC,
etc.) for online charging. The shape of the request body depends on
the configured file_type, which selects the parser and the rating
pipeline.

A typical flow:

1. Session start (record_type=start_request) - reserve units;
   BillRun returns a granted volume + transaction ID.
2. Session update (record_type=update_request) - mid-session
   re-authorization (consume, request additional units).
3. Session release (record_type=release_request) - settle the
   actual used volume and free any reservation.

Implementation: RealtimeController::execute() delegates to the
configured decoder (JSON / KV / Diameter-mapped). Returned codes
come from conf/realtime/return_codes.ini.

## Outgoing

Endpoints that **BillRun calls on a 3rd-party CRM** when running in
external-subscribers mode (accounts and subscribers are stored in the CRM,
not in BillRun). Implement these on the CRM side.


### [CRM] GBA - Get Billable Accounts

 - [POST /crm/billable](https://billrun.redocly.app/openapi.bundled/outgoing/outgoing.gba.md): Called by BillRun's cycle aggregator at cycle-close time to fetch
every account (with embedded subscriber revisions) that should be
billed in the requested window. The CRM must return the data
paginated - BillRun calls this repeatedly with increasing
page until the response runs out of rows.

Source: Billrun_Account_External::getBillable().

Request fields:

- start_date / end_date - cycle window. Formatted per the
  subscribers.billable.single_day_cycle_format config (default
  Y-m-d, or Y-m-d H:i:s for same-day cycles).
- page / size - pagination.
- aids - optional comma-separated AID filter, used when BillRun
  is rebilling a subset.
- invoicing_days - optional invoicing-day filter for tenants
  that split the cycle across multiple invoicing days.

Response must include a truthy status and a data array;
BillRun translates firstname->first_name and
lastname->last_name automatically on the way in.

### [CRM] GAD - Get Account Details

 - [POST /crm/account](https://billrun.redocly.app/openapi.bundled/outgoing/outgoing.gad.md): Fetch one or more account revisions by query. Used during rating
and on ad-hoc lookups. The CRM receives a JSON envelope with a
query array - each entry describes a set of params to match
and the effective time for the lookup.

Source: Billrun_Account_External::getAccountDetails() /
getAccountsDetails().

### [CRM] GSD - Get Subscriber Details

 - [POST /crm/subscriber](https://billrun.redocly.app/openapi.bundled/outgoing/outgoing.gsd.md): Fetch one or more subscriber revisions by query. Same envelope
shape as GAD - a query array of {id, time, params} entries.

Source: Billrun_Subscriber_External::getSubscriberDetails().

When subscribers.account.cache_gba_to_gsd.enabled is on, BillRun
pre-populates the local GSD cache from the previous GBA response
so the cycle close does not hammer this endpoint for every line
it rates.