Search

getBilledUntilDate

Retrieve “billed until” dates for recurring billings.

This API call calculates the end date of the last billed period for each specified billing. Check these dates against the parameters of respective billings to find out which customers are already due for their next invoice. Detailed information about each billing can be retrieved with API call getBillingStatements.

Most importantly, you need to know:

  • What is the period (cycle) of the recurring billing (field billingStatementPeriod);
  • Whether the customer is billed at the beginning of the billing period, at the end of the period, or is billing based on the readings of a meter (field billingStatementTime);
  • When recurring billing is supposed to begin and/or end (fields startDate and endDate).

For billings that are based on meter readings, a “billing period” is the time span from one reading to the next one; and the “billed until” date is the date of the last invoiced reading.

API returns “0000-00-00” for a particular billing if:

  • The billing has been set up, but no invoices have been issued yet. (In that case, refer to the billing’s “start date” instead.);
  • If the billing is currently suspended (deactivated);
  • If no readings have been entered yet, or only the initial reading of the meter has been entered.

Generally, recurring billing works best if invoices are issued in order. If there are any gaps in billing, back office and API at the moment treat fixed-fee billings and metered billings differently. For a fixed-fee billing, API returns the date of the most recent billed period; while for metered billings, API identifies the earliest “gap” in invoices (earliest reading that has not been invoiced yet) and returns the date of the reading before that.

Input parameters

Parameter nameDescriptionPossible valueRequired
billingStatementIDs

A comma-separated list of billing statement IDs, containing at most 500 IDs.

If the list contains more than 500 IDs, error code 1138 is returned.

.
String (comma-separated list of integers) yes

Response

Field nameTypeDescription
billingStatementIDIntegerBilling statement ID.
billedUntilISO date (yyyy-mm-dd)End date of the last billed period, or "0000-00-00" if the billing is deactivated, no invoices have been issued yet, or no readings have been entered yet.