Preview Bill

curl --request POST \
  --url https://api.m3ter.com/organizations/{orgId}/bills/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 123,
  "lastDateInBillingPeriod": "2023-12-25",
  "billingFrequency": "DAILY",
  "billFrequencyInterval": 123,
  "billDate": "2023-12-25",
  "externalInvoiceDate": "2023-12-25",
  "dueDate": "2023-12-25",
  "accountIds": [
    "<string>"
  ],
  "targetCurrency": "<string>",
  "currencyConversions": [
    {
      "from": "EUR",
      "to": "USD",
      "multiplier": 1.12
    }
  ],
  "timezone": "UTC",
  "yearEpoch": "2023-12-25",
  "monthEpoch": "2023-12-25",
  "weekEpoch": "2023-12-25",
  "dayEpoch": "2023-12-25"
}
'

{
  "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>"
}

Preview Bill

Preview the current Bill for a specific account.

This endpoint is designed to provide a preview of the Bill for exactly one account, allowing you to review charges, frequencies, and other details before finalization. Required parameters include:

accountIds - exactly 1 account must be specified for previewing a Bill.
billingFrequency
billFrequencyInterval

Other request parameters are optional. If version is not specified, the latest version of the Bill is previewed.

POST

organizations

{orgId}

bills

preview

Preview Bill

curl --request POST \
  --url https://api.m3ter.com/organizations/{orgId}/bills/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 123,
  "lastDateInBillingPeriod": "2023-12-25",
  "billingFrequency": "DAILY",
  "billFrequencyInterval": 123,
  "billDate": "2023-12-25",
  "externalInvoiceDate": "2023-12-25",
  "dueDate": "2023-12-25",
  "accountIds": [
    "<string>"
  ],
  "targetCurrency": "<string>",
  "currencyConversions": [
    {
      "from": "EUR",
      "to": "USD",
      "multiplier": 1.12
    }
  ],
  "timezone": "UTC",
  "yearEpoch": "2023-12-25",
  "monthEpoch": "2023-12-25",
  "weekEpoch": "2023-12-25",
  "dayEpoch": "2023-12-25"
}
'

{
  "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.

Query Parameters

debug

boolean | null

Body

application/json

version

integer<int64>

The version number of the entity:

Create entity: Not valid for initial insertion of new entity - do not use for Create. On initial Create, version is set at 1 and listed in the response.
Update Entity: On Update, version is required and must match the existing version because a check is performed to ensure sequential versioning is preserved. Version is incremented by 1 and listed in the response.

lastDateInBillingPeriod

string<date>

Specifies the date (in ISO 8601 format) of the last day in the billing period, defining the time range for the associated Bills.

For example: "2023-03-24".

billingFrequency

enum<string>

How often Bills are generated.

Daily. Starting at midnight each day, covering a twenty-four hour period following.
Weekly. Starting at midnight on a Monday morning covering the seven-day period following.
Monthly. Starting at midnight on the morning of the first day of each month covering the entire calendar month following.
Annually. Starting at midnight on the morning of the first day of each year covering the entire calendar year following.
Ad_Hoc. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule.

Available options:

DAILY,

WEEKLY,

MONTHLY,

ANNUALLY,

AD_HOC

billFrequencyInterval

integer<int32>

How often Bills are issued - used in conjunction with billingFrequency.

For example, if billingFrequency is set to Monthly and billFrequencyInterval is set to 3, Bills are issued every three months.

billDate

string<date>

The specific billing date (in ISO 8601 format), determining when the Bill was generated.

For example: "2023-01-24".

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). Used when you want to recognize usage revenue in the following period.
LAST_DAY_OF_ARREARS. Used when you want to recognize usage revenue in the same period that it's consumed, instead of in the following period.

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.

dueDate

string<date>

The due date (in ISO 8601 format) for payment of the Bill.

For example: "2023-02-24".

accountIds

string[]

An array of UUIDs representing the end customer Accounts associated with the BillJob.

Required array length: 1 - 100 elements

targetCurrency

string

The currency code used for the Bill, such as USD, GBP, or EUR.

Required string length: 3

currencyConversions

object[]

An array of currency conversion rates from Bill currency to Organization currency. For example, if Account is billed in GBP and Organization is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined rate.

Maximum array length: 250

Show child attributes

timezone

string

default:UTC

Specifies the time zone used for the generated Bills, ensuring alignment with the local time zone.

Example:

"UTC"

yearEpoch

string<date>

The starting date (epoch) for Yearly billing frequency (in ISO 8601 format), determining the first Bill date for yearly Bills.

monthEpoch

string<date>

The starting date (epoch) for Monthly billing frequency (in ISO 8601 format), determining the first Bill date for monthly Bills.

weekEpoch

string<date>

The starting date (epoch) for Weekly billing frequency (in ISO 8601 format), determining the first Bill date for weekly Bills.

dayEpoch

string<date>

The starting date (epoch) for Daily billing frequency (in ISO 8601 format), determining the first Bill date for daily Bills.

Response

Returns the Bill preview

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[]

Show child attributes

lastCalculatedDate

string<date-time>

lineItems

object[]

An array of the Bill line items.

Show child attributes

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

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.

Create Bill Statement in CSV Format

Retrieve Line Item Usage in JSON Format

⌘I

Getting Started

Endpoints

Preview Bill

Authorizations

Path Parameters

Query Parameters

Body

Response