Skip to main content
GET
/
organizations
/
{orgId}
/
bills
/
{id}
Retrieve Bill
curl --request GET \
  --url https://api.m3ter.com/organizations/{orgId}/bills/{id} \
  --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": {}
    }
  ],
  "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>"
}

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.

​
id
string
required

The unique identifier (UUID) of the Bill to retrieve.

Query Parameters

​
additional
string[]

Comma separated list of additional fields.

Response

Returns the requested Bill

​
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
​
accountCode
string
​
startDate
string<date>
​
endDate
string<date>
​
startDateTimeUTC
string<date-time>
​
endDateTimeUTC
string<date-time>
​
billDate
string<date>
​
dueDate
string<date>
​
billingFrequency
enum<string>
Available options:
DAILY,
WEEKLY,
MONTHLY,
ANNUALLY,
AD_HOC,
MIXED
​
billFrequencyInterval
integer<int32>
​
timezone
string
default:UTC
Example:

"UTC"

​
currency
string
​
locked
boolean
​
createdDate
string<date-time>
​
status
enum<string>
Available options:
PENDING,
APPROVED
​
billJobId
string
​
currencyConversions
object[]
​
lastCalculatedDate
string<date-time>
​
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.