Skip to main content
GET
/
organizations
/
{orgId}
/
bills
/
latest
/
{accountId}
Retrieve latest Bill
curl --request GET \
  --url https://api.m3ter.com/organizations/{orgId}/bills/latest/{accountId} \
  --header 'Authorization: Bearer <token>'
{
  "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.m3ter.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
accountId
string
required

The unique identifier (UUID) of the Account for which the latest Bill should be retrieved.

Query Parameters

​
additional
string[]

Comma separated list of additional fields.

Response

Returns the latest Bill for the given Account

​
id
string
required

The UUID of the entity.

​
version
integer<int64>

The version number:

  • Create: On initial Create to insert a new entity, the version is set at 1 in the response.
  • Update: On successful Update, the version is incremented by 1 in the response.
​
accountId
string

The unique identifier (UUID) of the Account the Bill was generated for.

​
accountCode
string

The short code of the Account the Bill was generated for.

​
startDate
string<date>
​
endDate
string<date>
​
startDateTimeUTC
string<date-time>

Specifies the UTC time zone start date/time of the Bill's period in ISO 8601 format. Start dates are inclusive.

For example: "2022-02-01T00:00:00.000Z".

​
endDateTimeUTC
string<date-time>

Specifies the UTC time zone end date/time of the Bill's period in ISO 8601 format. End dates are exclusive.

For example: "2022-03-01T00:00:00.000Z".

​
billDate
string<date>

Based on the Billing cycle. Typically the first day of each Billing period. Bill date is determined by Organization Epoch setting for first Bill date and subsequent Bill dates and combined with the defined billing frequency - daily, weekly, monthly, or yearly.

For example: "2022-05-01".

Note that the Organization Epoch settings for first Bill date can be overridden at Account and Plan level.

​
dueDate
string<date>

Date the Bill is due. Determined by daysBeforeBillDue Organization setting and billDate. For example, if billDate for monthly billing cycle is 1st of each month and daysBeforeBillDue = 10, then dueDate = 11th of each month.

For example: "2022-05-11".

​
billingFrequency
enum<string>

The period covered by the Bill on a recurring basis - DAILY, WEEKLY, MONTHLY, or ANNUALLY.

Available options:
DAILY,
WEEKLY,
MONTHLY,
ANNUALLY,
AD_HOC,
MIXED
​
billFrequencyInterval
integer<int32>

How often the Bill is created. If billingFrequency is MONTHLY and billFrequencyInterval is 3, then the Bill is created every three months.

​
timezone
string
default:UTC

The time zone used for the generated Bill.

Example:

"UTC"

​
currency
string

Bill Currency code. For example: USD, GBP or EUR.

​
locked
boolean

Boolean flag indicating whether the Bill is in a locked state. A locked a Bill can no longer be changed and is excluded from any billing runs:

  • TRUE - Bill is locked.
  • FALSE - Bill is unlocked.
​
createdDate
string<date-time>

Date/time the Bill was first calculated (in ISO 8601 format).

​
status
enum<string>

Indicates whether the Bill has been approved.

  • PENDING - Bill has not yet been approved.
  • APPROVED - Bill has been approved.
Available options:
PENDING,
APPROVED
​
billJobId
string

The unique identifier (UUID) of the BillJob responsible for generating the Bill.

​
currencyConversions
object[]

Currency conversion rates. The currency selected for your Organization determines the billing currency. This billing currency can differ from the pricing currency used when pricing Product Plans attached to end-customer Accounts:

  • For example, if an Account is priced in GBP and Organization billing currency is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined currency conversion rate.

If you intend to use different billing and pricing currencies, you must define currency conversion rates

​
lastCalculatedDate
string<date-time>

Date the Bill was last calculated (in ISO 8601 format).

​
lineItems
object[]

An array of the Bill line items.

​
purchaseOrderNumber
string

Purchase Order number linked to the Account the Bill is for.

​
externalInvoiceReference
string

The reference ID to use for external invoice.

​
externalInvoiceDate
string<date>

For accounting purposes, the date set at Organization level to use for external invoicing with respect to billing periods - two options:

  • FIRST_DAY_OF_NEXT_PERIOD (Default).
  • LAST_DAY_OF_ARREARS

For example, if the retrieved Bill was on a monthly billing frequency and the billing period for the Bill is September 2023 and the External invoice date is set at FIRST_DAY_OF_NEXT_PERIOD, then the externalInvoiceDate will be "2023-10-01".

NOTE: To change the externalInvoiceDate setting for your Organization, you can use the Update OrganizationConfig call.

​
jsonStatementGenerated
boolean

Flag to indicate that the statement in JSON format has been generated for the Bill.

  • TRUE - JSON statement has been generated.
  • FALSE - no JSON statement generated.
​
csvStatementGenerated
boolean

Flag to indicate that the statement in CSV format has been generated for the Bill.

  • TRUE - CSV statement has been generated.
  • FALSE - no CSV statement generated.
​
statementStale
boolean

True if the existing bill statement (JSON or CSV) is marked as stale/outdated.

​
billTotal
number

The sum total for the Bill.

​
sequentialInvoiceNumber
string

The sequential invoice number of the Bill.

NOTE: If you have not defined a billPrefix for your Organization, a sequentialInvoiceNumber is not returned in the response. See Update OrganizationConfig

​
dtCreated
string<date-time>

The date and time (in ISO 8601 format) when the Bill was first created.

​
dtLastModified
string<date-time>

The date and time (in ISO 8601 format) when the Bill was last modified.

​
createdBy
string

The unique identifier (UUID) for the user who created the Bill.

​
lastModifiedBy
string

The unique identifier (UUID) for the user who last modified this Bill.

​
dtApproved
string<date-time>

The DateTime when the bill was approved.

​
approvedBy
string

The id of the user who approved this bill.

​
dtLocked
string<date-time>

The DateTime when the bill was locked.

​
lockedBy
string

The id of the user who locked this bill.