List Bills

Retrieve a list of Bills.

This endpoint retrieves a list of all Bills for the given Account within the specified Organization. Optional filters can be applied such as by date range, lock status, or other attributes. The list can also be paginated for easier management.

GET /organizations/{orgId}/bills

List Bills

cURL

curl --request GET \
  --url https://api.m3ter.com/organizations/{orgId}/bills \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "id": "<string>",
      "version": 123,
      "accountId": "<string>",
      "accountCode": "<string>",
      "startDate": "2023-12-25",
      "endDate": "2023-12-25",
      "startDateTimeUTC": "2023-11-07T05:31:56Z",
      "endDateTimeUTC": "2023-11-07T05:31:56Z",
      "billDate": "2023-12-25",
      "dueDate": "2023-12-25",
      "billingFrequency": "DAILY",
      "billFrequencyInterval": 123,
      "timezone": "UTC",
      "currency": "<string>",
      "locked": true,
      "createdDate": "2023-11-07T05:31:56Z",
      "status": "PENDING",
      "billJobId": "<string>",
      "currencyConversions": [
        {
          "from": "EUR",
          "to": "USD",
          "multiplier": 1.12
        }
      ],
      "lastCalculatedDate": "2023-11-07T05:31:56Z",
      "lineItems": [
        {
          "description": "<string>",
          "quantity": 123,
          "units": 123,
          "unit": "<string>",
          "subtotal": 123,
          "currency": "<string>",
          "conversionRate": 123,
          "convertedSubtotal": 123,
          "lineItemType": "STANDING_CHARGE",
          "averageUnitPrice": 123,
          "id": "<string>",
          "productId": "<string>",
          "productName": "<string>",
          "productCode": "<string>",
          "accountingProductId": "<string>",
          "accountingProductName": "<string>",
          "accountingProductCode": "<string>",
          "aggregationId": "<string>",
          "compoundAggregationId": "<string>",
          "counterId": "<string>",
          "chargeId": "<string>",
          "segment": {},
          "group": {},
          "meterId": "<string>",
          "planId": "<string>",
          "planGroupId": "<string>",
          "commitmentId": "<string>",
          "balanceId": "<string>",
          "creditTypeId": "<string>",
          "pricingId": "<string>",
          "childAccountId": "<string>",
          "childAccountCode": "<string>",
          "usagePerPricingBand": [
            {
              "pricingBandId": "<string>",
              "lowerLimit": 123,
              "fixedPrice": 123,
              "unitSubtotal": 123,
              "unitPrice": 123,
              "bandUnits": 123,
              "bandQuantity": 123,
              "bandSubtotal": 123,
              "creditTypeId": "<string>",
              "convertedBandSubtotal": 123
            }
          ],
          "servicePeriodStartDate": "2023-11-07T05:31:56Z",
          "servicePeriodEndDate": "2023-11-07T05:31:56Z",
          "referencedBillId": "<string>",
          "referencedLineItemId": "<string>",
          "reasonId": "<string>",
          "contractId": "<string>",
          "sequenceNumber": 123,
          "additional": {},
          "grantDrawdowns": [
            {
              "balanceId": "<string>",
              "quantity": 123,
              "units": 123,
              "currencyAmount": 123
            }
          ],
          "balanceDrawdowns": [
            {
              "balanceId": "<string>",
              "units": 123,
              "balanceAmount": 123,
              "lineItemAmount": 123,
              "billAmount": 123
            }
          ],
          "commitmentDrawdowns": [
            {
              "commitmentId": "<string>",
              "units": 123,
              "commitmentAmount": 123,
              "lineItemAmount": 123,
              "billAmount": 123
            }
          ],
          "creditCoverage": [
            {
              "lineItemId": "<string>",
              "units": 123,
              "lineItemAmount": 123,
              "creditAmount": 123,
              "billAmount": 123
            }
          ]
        }
      ],
      "purchaseOrderNumber": "<string>",
      "externalInvoiceReference": "<string>",
      "externalInvoiceDate": "2023-12-25",
      "jsonStatementGenerated": true,
      "csvStatementGenerated": true,
      "statementStale": true,
      "billTotal": 123,
      "sequentialInvoiceNumber": "<string>",
      "dtCreated": "2023-11-07T05:31:56Z",
      "dtLastModified": "2023-11-07T05:31:56Z",
      "createdBy": "<string>",
      "lastModifiedBy": "<string>",
      "dtApproved": "2023-11-07T05:31:56Z",
      "approvedBy": "<string>",
      "dtLocked": "2023-11-07T05:31:56Z",
      "lockedBy": "<string>"
    }
  ],
  "nextToken": "<string>"
}

Authorizations

Authorization · string · header · required

m3ter supports machine to machine authentication using the clientCredentials OAuth2 flow.

The authorizationCode flow controls access for human users via the m3ter Console application.

Path Parameters

orgId · string · required

The unique identifier (UUID) of your Organization. The Organization represents your company as a direct customer of our service.

Query Parameters

pageSize · integer<int32>

Specifies the maximum number of Bills to retrieve per page.

Required range: 1 <= x <= 100

nextToken · string

The nextToken for multi-page retrievals. It is used to fetch the next page of Bills in a paginated list.

accountId · string

Optional filter. An Account ID - returns the Bills for the single specified Account.

locked · boolean

Boolean flag specifying whether to include Bills with "locked" status.

• TRUE - the list inlcudes "locked" Bills.
• FALSE - excludes "locked" Bills from the list.

excludeLineItems · boolean

Exclude Line Items

includeBillTotal · boolean

Include Bill Total

status · enum<string>

Only include Bills having the given status Indicates whether the Bill has passed human/manual approval.

• Pending - Bill has not yet been passed by a human reviewer.
• Approved - Bill has been approved after manual review.

Available options: PENDING, APPROVED

billDate · string

The specific date (in ISO 8601 format) for which you want to retrieve Bills.

billDateStart · string

Only include Bills with bill date equal to or later than this date (in ISO-8601 format).

billDateEnd · string

Only include Bills with bill dates earlier than this date (in ISO-8601 format).

externalInvoiceDateStart · string

Only include Bills with external invoice dates equal to or later than this date (in ISO-8601 format).

externalInvoiceDateEnd · string

Only include Bills with external invoice dates earlier than this date (in ISO-8601 format).

ids · string

Optional filter. The list of Bill IDs to retrieve.

billJobId · string

List Bill entities by the bill job that last calculated them.

additional · string[]

Comma separated list of additional fields.

billingFrequency · string | null

Only include Bills using the specified bill frequency:

• DAILY
• WEEKLY
• MONTHLY
• ANNUALLY

IMPORTANT!: Can only be used with the billDate query parameter.

Response

200

application/json

Returns the requested list of Bills

data · object[]

Show child attributes

nextToken · string