Skip to main content
GET
/
organizations
/
{orgId}
/
billjobs
/
{id}
Retrieve BillJob
curl --request GET \
  --url https://api.m3ter.com/organizations/{orgId}/billjobs/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "version": 123,
  "lastDateInBillingPeriod": "2023-12-25",
  "billingFrequency": "DAILY",
  "billFrequencyInterval": 123,
  "billDate": "2023-12-25",
  "externalInvoiceDate": "2023-12-25",
  "dueDate": "2023-12-25",
  "accountIds": [
    "<string>"
  ],
  "billIds": [
    "<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",
  "status": "PENDING",
  "total": 123,
  "pending": 123,
  "type": "CREATE",
  "dtCreated": "2023-11-07T05:31:56Z",
  "dtLastModified": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "lastModifiedBy": "<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

UUID of the organization

​
id
string
required

The UUID of the Bill Job to retrieve.

Response

Returns the Bill Job

​
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.
​
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>

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

​
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.

​
billIds
string[]

An array of Bill IDs related to the BillJob, providing references to the specific Bills generated.

​
targetCurrency
string

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

​
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.

​
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.

​
status
enum<string>

The current status of the BillJob, indicating its progress or completion state.

Available options:
PENDING,
INITIALIZING,
RUNNING,
COMPLETE,
CANCELLED
​
total
integer<int64>

The total number of Bills or calculations related to the BillJob.

​
pending
integer<int64>

The number of pending actions or calculations within the BillJob.

​
type
enum<string>

Specifies the type of BillJob.

  • CREATE Returned for a Create BillJob call.
  • RECALCULATE Returned for a successful Create Recalculation BillJob call.
Available options:
CREATE,
RECALCULATE
​
dtCreated
string<date-time>

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

​
dtLastModified
string<date-time>

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

​
createdBy
string

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

​
lastModifiedBy
string

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