Get Bulk Billing V1

This page documents version 1 of the Get Bulk Billing end point.

Data Holders MUST implement Get Bulk Billing v2 by November 1st 2023.
This version is to be ceased to be called by data recipients by September 9th 2024 and can be decommissioned by data holders as of that date.
Support for this version is not required for Data Holders going live on, or after, November 1st 2023.

Get Bulk Billing

Code samples

GET /energy/accounts/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

var 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'

};

$.ajax({
  url: '/energy/accounts/billing',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

GET /energy/accounts/billing

Obtain billing transactions for all accounts

Endpoint Version


Version	1

Parameters

Name	In	Type	Required	Description
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-R-Draft]. 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	EnergyBillingListResponse
400	Bad Request	The following error codes MUST be supported: 400 - Invalid Field 400 - Invalid Page Size 400 - Invalid Version	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.
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.

EnergyBillingListResponse

{
  "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	[EnergyBillingTransaction]	mandatory	Array of transactions sorted by date and time in descending order
links	LinksPaginated	mandatory	none
meta	MetaPaginated	mandatory	none

EnergyBillingTransaction

{
  "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	string	mandatory	Indicator of the type of transaction object present in this record
usage	EnergyBillingUsageTransaction	conditional	Represents a usage charge or generation credit. Mandatory if transactionUType is equal to usage
demand	EnergyBillingDemandTransaction	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

EnergyBillingUsageTransaction

{
  "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	string	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	string	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	string	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
measureUnit	KWH
measureUnit	KVA
measureUnit	KVAR
measureUnit	KVARH
measureUnit	KW
measureUnit	DAYS
measureUnit	METER
measureUnit	MONTH
type	DLF
type	MLF

EnergyBillingDemandTransaction

{
  "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	string	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	string	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
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	string	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	string	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	string	mandatory	The method of payment

Enumerated Values

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

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.

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.