Organization billing statements

In this section, we walk through understanding organization billing statements in BILL. BILL generates a monthly billing invoice statement for all the billing activities in an organization.

Get list of billing statements

In your GET /v3/organizations/{organizationId}/billing-statements request, set the organizationId for the organization. The value begins with 008. All the query parameters are optional.

See the GET /v3/organizations/{organizationId}/billing-statements API for more information about the other fields you can set.

Sample request

In this cURL example, we list billing statements and filter with the invoiceDateFrom and invoiceDateTo fields.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/organizations/{organization_id}/billing-statements?invoiceDateFrom=2026-05-01&invoiceDateTo=2026-06-30' \
--header 'accept: application/json'
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, a BILL-generated billing statement id is available for each billing statement that matches the filter in the request. The value begins with 0S0. In addition, we get a summary of each billing statement.

[
  {
    "id": "{billing_statement_id01}",
    "invoiceNumber": "{invoice_number01}",
    "invoiceDate": "2026-06-16",
    "description": "{description}",
    "billingPeriod": {
      "startDate": "2026-05-16",
      "endDate": "2026-06-16"
    },
    "paymentStatus": "PAID",
    "paymentDate": "2026-09-18",
    "amount": 160.44
  },
  {
    "id": "{billing_statement_id02}",
    "invoiceNumber": "{invoice_number02}",
    "invoiceDate": "2026-05-16",
    "description": "{description}",
    "billingPeriod": {
      "startDate": "2026-04-16",
      "endDate": "2026-05-16"
    },
    "paymentStatus": "PAID",
    "paymentDate": "2026-06-01",
    "amount": 167.56
  }
]

Get billing statement details

In your GET /v3/organizations/{organizationId}/billing-statements/{billingStatementId} request, set the required path parameters.

Field	Description
`organizationId`	BILL-generated ID of the organization. The value begins with `008`.
`billingStatementId`	BILL-generated ID of the billing statement. The value begins with `0S0`.

Sample response

In the response, we get the summary of the current billing statement. In addition to the summary of the billing statement, we get additional information.

Field	Description
`statementDetails`	Statement details. This includes billing invoice line item information.
`downloadLink`	Billing statement download link information. You can use the CSV or PDF link in a `GET` request to download the billing statement. See GET /v3/organizations/{organizationId}/billing-statements/{billingStatementId} in the API reference for more information.

{
  "id": "{billing_statement_id}",
  "invoiceNumber": "{invoice_number}",
  "invoiceDate": "2026-08-16",
  "billingPeriod": {
    "startDate": "2026-07-16",
    "endDate": "2026-08-16"
  },
  "paymentStatus": "PAID",
  "amount": 2685.19,
  "statementDetails": [
    {
      "quantity": 1,
      "type": "User",
      "description": "First user free",
      "amount": 0.00
    },
    {
      "quantity": 5,
      "type": "User",
      "description": "$10/user for next 10 users",
      "amount": 50.00
    },
    {
      "quantity": 10,
      "type": "BILL Pmt (US Check)",
      "description": "First 10 payments free",
      "amount": 0.00
    },
    {
      "quantity": 2081,
      "type": "BILL Pmt (US Check)",
      "description": "$0.99/payment",
      "amount": 2060.19
    },
    {
      "quantity": 1,
      "type": "Company Subscription",
      "description": "$25/company",
      "amount": 25.00
    },
    {
      "quantity": 55,
      "type": "BILL Intl Payment (FX Wire)",
      "description": "Test by Ramya",
      "amount": 550.00
    },
    {
      "quantity": 14,
      "type": "Card Funded US Check",
      "description": "US Mail - PayByCard",
      "amount": 0.00
    },
    {
      "quantity": 5,
      "type": "Card Funded AR ePayment",
      "description": "ePayment - Instapay",
      "amount": 0.00
    }
  ],
  "downloadLink": {
    "csv": "{csv_download_link}",
    "pdf": "{pdf_download_link}"
  }
}