Get Billing For Account V2

This page documents version 2 of the Get Billing For Account end point.

Data Holders MAY retire this version on September 9th 2024 if they implement v3.

Get Billing For Account

Code samples

GET /energy/accounts/{accountId}/billing HTTP/1.1

Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-v':'string',
  'x-min-v':'string',
  'x-fapi-interaction-id':'string',
  'x-fapi-auth-date':'string',
  'x-fapi-customer-ip-address':'string',
  'x-cds-client-headers':'string'

};

fetch('/energy/accounts/{accountId}/billing',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /energy/accounts/{accountId}/billing

Obtain the billing transactions for a specific account

Other Versions: v1

Endpoint Version


Version	2

Parameters

Name	In	Type	Required	Description
accountId	path	string	mandatory	ID of a specific account to obtain data for. This is a tokenised ID previous obtained from the Account List end point.
newest-time	query	DateTimeString	optional	Constrain the request to records with effective time at or before this date/time. If absent defaults to current date/time. Format is aligned to DateTimeString common type
oldest-time	query	DateTimeString	optional	Constrain the request to records with effective time at or after this date/time. If absent defaults to newest-time minus 12 months. Format is aligned to DateTimeString common type
page	query	PositiveInteger	optional	Page of results to request (standard pagination)
page-size	query	PositiveInteger	optional	Page size to request. Default is 25 (standard pagination)
x-v	header	string	mandatory	Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers
x-min-v	header	string	optional	Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable.
x-fapi-interaction-id	header	string	optional	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
x-fapi-auth-date	header	string	conditional	The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
x-fapi-customer-ip-address	header	string	optional	The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
x-cds-client-headers	header	Base64	conditional	The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.

Example responses

200 Response

{
  "data": {
    "transactions": [
      {
        "accountId": "string",
        "executionDateTime": "string",
        "gst": "string",
        "transactionUType": "usage",
        "usage": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "timeOfUseType": "PEAK",
          "description": "string",
          "isEstimate": true,
          "startDate": "string",
          "endDate": "string",
          "measureUnit": "KWH",
          "usage": 0,
          "amount": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "demand": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "timeOfUseType": "PEAK",
          "description": "string",
          "isEstimate": true,
          "startDate": "string",
          "endDate": "string",
          "rate": 0,
          "amount": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "onceOff": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "amount": "string",
          "description": "string"
        },
        "otherCharges": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "startDate": "string",
          "endDate": "string",
          "type": "ENVIRONMENTAL",
          "amount": "string",
          "description": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "payment": {
          "amount": "string",
          "method": "DIRECT_DEBIT"
        }
      }
    ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  },
  "meta": {
    "totalRecords": 0,
    "totalPages": 0
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful response	EnergyBillingListResponseV2
400	Bad Request	The following error codes MUST be supported: 400 - Invalid Field 400 - Missing Field 400 - Invalid Date 400 - Invalid Page Size 400 - Invalid Version	ResponseErrorListV2
404	Not Found	The following error codes MUST be supported: 404 - Unavailable Energy Account 404 - Invalid Energy Account	ResponseErrorListV2
406	Not Acceptable	The following error codes MUST be supported: 406 - Unsupported Version	ResponseErrorListV2
422	Unprocessable Entity	The following error codes MUST be supported: 422 - Invalid Page	ResponseErrorListV2

Response Headers

Status	Header	Type	Description
200	x-v	string	The version of the API end point that the data holder has responded with.
200	x-fapi-interaction-id	string	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
400	x-fapi-interaction-id	string	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
404	x-fapi-interaction-id	string	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
406	x-fapi-interaction-id	string	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
422	x-fapi-interaction-id	string	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.

Schemas

EnergyBillingListResponseV2

{
  "data": {
    "transactions": [
      {
        "accountId": "string",
        "executionDateTime": "string",
        "gst": "string",
        "transactionUType": "usage",
        "usage": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "timeOfUseType": "PEAK",
          "description": "string",
          "isEstimate": true,
          "startDate": "string",
          "endDate": "string",
          "measureUnit": "KWH",
          "usage": 0,
          "amount": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "demand": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "timeOfUseType": "PEAK",
          "description": "string",
          "isEstimate": true,
          "startDate": "string",
          "endDate": "string",
          "rate": 0,
          "amount": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "onceOff": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "amount": "string",
          "description": "string"
        },
        "otherCharges": {
          "servicePointId": "string",
          "invoiceNumber": "string",
          "startDate": "string",
          "endDate": "string",
          "type": "ENVIRONMENTAL",
          "amount": "string",
          "description": "string",
          "calculationFactors": [
            {
              "value": 0,
              "type": "DLF"
            }
          ],
          "adjustments": [
            {
              "amount": "string",
              "description": "string"
            }
          ]
        },
        "payment": {
          "amount": "string",
          "method": "DIRECT_DEBIT"
        }
      }
    ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  },
  "meta": {
    "totalRecords": 0,
    "totalPages": 0
  }
}

Properties

Name	Type	Required	Description
data	object	mandatory	none
» transactions	[EnergyBillingTransactionV2]	mandatory	Array of transactions sorted by date and time in descending order
links	LinksPaginated	mandatory	none
meta	MetaPaginated	mandatory	none

ResponseErrorListV2

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "meta": {
        "urn": "string"
      }
    }
  ]
}

Properties

Name	Type	Required	Description
errors	[object]	mandatory	none
» code	string	mandatory	The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the meta object. Otherwise, the value is the error code URN.
» title	string	mandatory	A short, human-readable summary of the problem that MUST NOT change from occurrence to occurrence of the problem represented by the error code.
» detail	string	mandatory	A human-readable explanation specific to this occurrence of the problem.
» meta	object	optional	Additional data for customised error codes
»» urn	string	conditional	The CDR error code URN which the application-specific error code extends. Mandatory if the error `code` is an application-specific error rather than a standardised error code.

EnergyBillingTransactionV2

{
  "accountId": "string",
  "executionDateTime": "string",
  "gst": "string",
  "transactionUType": "usage",
  "usage": {
    "servicePointId": "string",
    "invoiceNumber": "string",
    "timeOfUseType": "PEAK",
    "description": "string",
    "isEstimate": true,
    "startDate": "string",
    "endDate": "string",
    "measureUnit": "KWH",
    "usage": 0,
    "amount": "string",
    "calculationFactors": [
      {
        "value": 0,
        "type": "DLF"
      }
    ],
    "adjustments": [
      {
        "amount": "string",
        "description": "string"
      }
    ]
  },
  "demand": {
    "servicePointId": "string",
    "invoiceNumber": "string",
    "timeOfUseType": "PEAK",
    "description": "string",
    "isEstimate": true,
    "startDate": "string",
    "endDate": "string",
    "rate": 0,
    "amount": "string",
    "calculationFactors": [
      {
        "value": 0,
        "type": "DLF"
      }
    ],
    "adjustments": [
      {
        "amount": "string",
        "description": "string"
      }
    ]
  },
  "onceOff": {
    "servicePointId": "string",
    "invoiceNumber": "string",
    "amount": "string",
    "description": "string"
  },
  "otherCharges": {
    "servicePointId": "string",
    "invoiceNumber": "string",
    "startDate": "string",
    "endDate": "string",
    "type": "ENVIRONMENTAL",
    "amount": "string",
    "description": "string",
    "calculationFactors": [
      {
        "value": 0,
        "type": "DLF"
      }
    ],
    "adjustments": [
      {
        "amount": "string",
        "description": "string"
      }
    ]
  },
  "payment": {
    "amount": "string",
    "method": "DIRECT_DEBIT"
  }
}

Properties

Name	Type	Required	Description
accountId	string	mandatory	The ID of the account for which transaction applies
executionDateTime	DateTimeString	mandatory	The date and time that the transaction occurred
gst	AmountString	optional	The GST incurred in the transaction. Should not be included for credits or payments. If absent zero is assumed
transactionUType	Enum	mandatory	Indicator of the type of transaction object present in this record
usage	EnergyBillingUsageTransactionV2	conditional	Represents a usage charge or generation credit. Mandatory if transactionUType is equal to usage
demand	EnergyBillingDemandTransactionV2	optional	Represents a demand charge or generation credit. Mandatory if transactionUType is equal to demand
onceOff	EnergyBillingOnceOffTransaction	conditional	Represents a once off charge or credit. Mandatory if transactionUType is equal to onceOff
otherCharges	EnergyBillingOtherTransaction	optional	Represents charge other than usage and once off. Mandatory if transactionUType is equal to otherCharge
payment	EnergyBillingPaymentTransaction	conditional	Represents a payment to the account. Mandatory if transactionUType is equal to payment

Enumerated Values

Property	Value
transactionUType	usage
transactionUType	demand
transactionUType	onceOff
transactionUType	otherCharges
transactionUType	payment

EnergyBillingUsageTransactionV2

{
  "servicePointId": "string",
  "invoiceNumber": "string",
  "timeOfUseType": "PEAK",
  "description": "string",
  "isEstimate": true,
  "startDate": "string",
  "endDate": "string",
  "measureUnit": "KWH",
  "usage": 0,
  "amount": "string",
  "calculationFactors": [
    {
      "value": 0,
      "type": "DLF"
    }
  ],
  "adjustments": [
    {
      "amount": "string",
      "description": "string"
    }
  ]
}

Properties

Name	Type	Required	Description
servicePointId	string	optional	The ID of the service point to which this transaction applies if any
invoiceNumber	string	optional	The number of the invoice in which this transaction is included if it has been issued
timeOfUseType	Enum	mandatory	The time of use type that the transaction applies to
description	string	optional	Optional description of the transaction that can be used for display purposes
isEstimate	boolean	optional	Flag indicating if the usage is estimated or actual. True indicates estimate. False or absent indicates actual
startDate	DateTimeString	mandatory	Date and time when the usage period starts
endDate	DateTimeString	mandatory	Date and time when the usage period ends
measureUnit	Enum	optional	The measurement unit of rate. Assumed to be KWH if absent
usage	number	mandatory	The usage for the period in measure unit. A negative value indicates power generated
amount	AmountString	mandatory	The amount charged or credited for this transaction prior to any adjustments being applied. A negative value indicates a credit
calculationFactors	[object]	optional	Additional calculation factors that inform the transaction
» value	number	mandatory	The value of the calculation factor
» type	Enum	mandatory	The type of the calculation factor
adjustments	[object]	optional	Optional array of adjustments arising for this transaction
» amount	AmountString	mandatory	The amount of the adjustment
» description	string	mandatory	A free text description of the adjustment

Enumerated Values

Property	Value
timeOfUseType	PEAK
timeOfUseType	OFF_PEAK
timeOfUseType	OFF_PEAK_DEMAND_CHARGE
timeOfUseType	SHOULDER
timeOfUseType	SHOULDER1
timeOfUseType	SHOULDER2
timeOfUseType	CONTROLLED_LOAD
timeOfUseType	SOLAR
timeOfUseType	AGGREGATE
timeOfUseType	ALL_DAY
measureUnit	KWH
measureUnit	KVA
measureUnit	KVAR
measureUnit	KVARH
measureUnit	KW
measureUnit	DAYS
measureUnit	METER
measureUnit	MONTH
type	DLF
type	MLF

EnergyBillingDemandTransactionV2

{
  "servicePointId": "string",
  "invoiceNumber": "string",
  "timeOfUseType": "PEAK",
  "description": "string",
  "isEstimate": true,
  "startDate": "string",
  "endDate": "string",
  "rate": 0,
  "amount": "string",
  "calculationFactors": [
    {
      "value": 0,
      "type": "DLF"
    }
  ],
  "adjustments": [
    {
      "amount": "string",
      "description": "string"
    }
  ]
}

Properties

Name	Type	Required	Description
servicePointId	string	optional	The ID of the service point to which this transaction applies if any
invoiceNumber	string	optional	The number of the invoice in which this transaction is included if it has been issued
timeOfUseType	Enum	mandatory	The time of use type that the transaction applies to
description	string	optional	Optional description of the transaction that can be used for display purposes
isEstimate	boolean	optional	Flag indicating if the usage is estimated or actual. True indicates estimate. False or absent indicates actual
startDate	DateTimeString	mandatory	Date and time when the demand period starts
endDate	DateTimeString	mandatory	Date and time when the demand period ends
rate	number	mandatory	The rate for the demand charge in kVA. A negative value indicates power generated
amount	AmountString	mandatory	The amount charged or credited for this transaction prior to any adjustments being applied. A negative value indicates a credit
calculationFactors	[object]	optional	Additional calculation factors that inform the transaction
» value	number	mandatory	The value of the calculation factor
» type	Enum	mandatory	The type of the calculation factor
adjustments	[object]	optional	Optional array of adjustments arising for this transaction
» amount	AmountString	mandatory	The amount of the adjustment
» description	string	mandatory	A free text description of the adjustment

Enumerated Values

Property	Value
timeOfUseType	PEAK
timeOfUseType	OFF_PEAK
timeOfUseType	OFF_PEAK_DEMAND_CHARGE
timeOfUseType	SHOULDER
timeOfUseType	SHOULDER1
timeOfUseType	SHOULDER2
timeOfUseType	CONTROLLED_LOAD
timeOfUseType	SOLAR
timeOfUseType	AGGREGATE
timeOfUseType	ALL_DAY
timeOfUseType	EXCESS
type	DLF
type	MLF

EnergyBillingOnceOffTransaction

{
  "servicePointId": "string",
  "invoiceNumber": "string",
  "amount": "string",
  "description": "string"
}

Properties

Name	Type	Required	Description
servicePointId	string	optional	The ID of the service point to which this transaction applies if any
invoiceNumber	string	optional	The number of the invoice in which this transaction is included if it has been issued
amount	AmountString	mandatory	The amount of the charge or credit. A positive value indicates a charge and a negative value indicates a credit
description	string	mandatory	A free text description of the item

EnergyBillingOtherTransaction

{
  "servicePointId": "string",
  "invoiceNumber": "string",
  "startDate": "string",
  "endDate": "string",
  "type": "ENVIRONMENTAL",
  "amount": "string",
  "description": "string",
  "calculationFactors": [
    {
      "value": 0,
      "type": "DLF"
    }
  ],
  "adjustments": [
    {
      "amount": "string",
      "description": "string"
    }
  ]
}

Properties

Name	Type	Required	Description
servicePointId	string	optional	The ID of the service point to which this transaction applies if any
invoiceNumber	string	optional	The number of the invoice in which this transaction is included if it has been issued
startDate	DateString	optional	Optional start date for the application of the charge
endDate	DateString	optional	Optional end date for the application of the charge
type	Enum	optional	Type of charge. Assumed to be other if absent
amount	AmountString	mandatory	The amount of the charge
description	string	mandatory	A free text description of the item
calculationFactors	[object]	optional	Additional calculation factors that inform the transaction
» value	number	mandatory	The value of the calculation factor
» type	Enum	mandatory	The type of the calculation factor
adjustments	[object]	optional	Optional array of adjustments arising for this transaction
» amount	AmountString	mandatory	The amount of the adjustment
» description	string	mandatory	A free text description of the adjustment

Enumerated Values

Property	Value
type	ENVIRONMENTAL
type	REGULATED
type	NETWORK
type	METERING
type	RETAIL_SERVICE
type	RCTI
type	OTHER
type	DLF
type	MLF

EnergyBillingPaymentTransaction

{
  "amount": "string",
  "method": "DIRECT_DEBIT"
}

Properties

Name	Type	Required	Description
amount	AmountString	mandatory	The amount paid
method	Enum	mandatory	The method of payment

Enumerated Values

Property	Value
method	DIRECT_DEBIT
method	CARD
method	TRANSFER
method	BPAY
method	CASH
method	CHEQUE
method	OTHER

LinksPaginated

{
  "self": "string",
  "first": "string",
  "prev": "string",
  "next": "string",
  "last": "string"
}

Properties

Name	Type	Required	Description
self	URIString	mandatory	Fully qualified link that generated the current response document
first	URIString	conditional	URI to the first page of this set. Mandatory if this response is not the first page
prev	URIString	conditional	URI to the previous page of this set. Mandatory if this response is not the first page
next	URIString	conditional	URI to the next page of this set. Mandatory if this response is not the last page
last	URIString	conditional	URI to the last page of this set. Mandatory if this response is not the last page

MetaPaginated

{
  "totalRecords": 0,
  "totalPages": 0
}

Properties

Name	Type	Required	Description
totalRecords	NaturalNumber	mandatory	The total number of records in the full set. See pagination.
totalPages	NaturalNumber	mandatory	The total number of pages in the full set. See pagination.