Jump to

• Request
• Response

Get Billing Usage

get

/apis/usage-v1/usage/billing/{utilityCode}/{utilityCustomerId}/{fuelType}

Returns the billing usage data for the given time period. Billing data can be returned for up to 25 bills in a single request. Data is available for the last two years preceding the time of the API request. If the active utility account is associated with multiple service points of the same fuel type billed usage per service point is returned.

Request

Path Parameters

• fuelType(required): string
  Fuel type to query for; ELECTRICITY or GAS
• id(required): integer
  The single-tenant id for the customer (e.g. `1`).
• utilityCode(required): string
  The 3 or 4 digit code for the utility company (e.g. `TEST`).

Query Parameters

• end(required): string
  End date in ISO-8601 format YYYY-MM-DD (example 2001-12-31) or YYYY-MM-DDThh:mm:ssTZD (example 2001-12-31T23:59:59-05:00) or YYYY-MM-DDThh:mm:ss.sTZD. Use -00:00 for UTC as Z is not currently supported. The + character is a reserved character in URIs, use its encoding %2B.
• start(required): string
  Start date in ISO-8601 format YYYY-MM-DD (example 2001-12-31) or YYYY-MM-DDThh:mm:ssTZD (example 2001-12-31T23:59:59-05:00) or YYYY-MM-DDThh:mm:ss.sTZD. Use -00:00 for UTC as Z is not currently supported. The + character is a reserved character in URIs, use its encoding %2B.

Header Parameters

• Authorization(required): string
  The authorization header (e.g. `Authorization: Bearer $YOUR_TOKEN`).

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful response

Body ()

Root Schema : BillingUsageResponse

Type: object

Show Source

• end(required): string
  The end date in the request
• fuelType(required): string
  The fuel type in the request
• start(required): string
  The start date in the request
• streams(required): array streams
• timezone(required): string
  The time zone of the service point location, expressed in ISO-8601 format. The time zone is used to define the day ranges for energy use.
• unit(required): string
  The unit of measurement of all fuel usage values
• utilityCode(required): string
  The 3 or 4 character code for the utility company; for example util.
• utilityCustomerId(required): string
  The utility customer identifier in the request

{
    "type":"object",
    "required":[
        "utilityCode",
        "utilityCustomerId",
        "fuelType",
        "start",
        "end",
        "timezone",
        "unit",
        "streams"
    ],
    "properties":{
        "utilityCode":{
            "type":"string",
            "description":"The 3 or 4 character code for the utility company; for example util."
        },
        "utilityCustomerId":{
            "type":"string",
            "description":"The utility customer identifier in the request"
        },
        "fuelType":{
            "type":"string",
            "description":"The fuel type in the request"
        },
        "start":{
            "type":"string",
            "description":"The start date in the request"
        },
        "end":{
            "type":"string",
            "description":"The end date in the request"
        },
        "timezone":{
            "type":"string",
            "description":"The time zone of the service point location, expressed in ISO-8601 format. The time zone is used to define the day ranges for energy use."
        },
        "unit":{
            "type":"string",
            "description":"The unit of measurement of all fuel usage values"
        },
        "streams":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/BillingUsageStream"
            }
        }
    },
    "example":{
        "response":{
            "utilityCode":"util",
            "utilityCustomerId":"9999990000-9999990000",
            "fuelType":"ELECTRICITY",
            "start":"2016-09-01T00:00:00.000-06:00",
            "end":"2016-11-01T00:00:00.000-06:00",
            "timezone":"America/New_York",
            "unit":"KWH",
            "streams":[
                {
                    "utilityServicePointId":"12345001",
                    "intervals":[
                        {
                            "start":"2016-09-29T00:00:00.000-04:00",
                            "end":"2016-10-28T00:00:00.000-04:00",
                            "billDate":"2016-10-27",
                            "usage":402,
                            "providedCost":65.98,
                            "readType":"ACTUAL"
                        }
                    ]
                }
            ]
        }
    }
}

Example:

{
    "response":{
        "utilityCode":"util",
        "utilityCustomerId":"9999990000-9999990000",
        "fuelType":"ELECTRICITY",
        "start":"2016-09-01T00:00:00.000-06:00",
        "end":"2016-11-01T00:00:00.000-06:00",
        "timezone":"America/New_York",
        "unit":"KWH",
        "streams":[
            {
                "utilityServicePointId":"12345001",
                "intervals":[
                    {
                        "start":"2016-09-29T00:00:00.000-04:00",
                        "end":"2016-10-28T00:00:00.000-04:00",
                        "billDate":"2016-10-27",
                        "usage":402,
                        "providedCost":65.98,
                        "readType":"ACTUAL"
                    }
                ]
            }
        ]
    }
}

Nested Schema : streams

Type: array

Show Source

• Array of: object BillingUsageStream

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/BillingUsageStream"
    }
}

Nested Schema : BillingUsageStream

Type: object

Show Source

• intervals(required): array intervals
• utilityServicePointId(required): string

{
    "type":"object",
    "required":[
        "utilityServicePointId",
        "intervals"
    ],
    "properties":{
        "utilityServicePointId":{
            "type":"string"
        },
        "intervals":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/BillingUsageInterval"
            }
        }
    }
}

Nested Schema : intervals

Type: array

Show Source

• Array of: object BillingUsageInterval

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/BillingUsageInterval"
    }
}

Nested Schema : BillingUsageInterval

Type: object

Show Source

• billDate(required): string
  The end date of meter read period.
• end(required): string
  The end of the period. This is an exclusive date/time String in ISO8601 format.
• providedCost: number
  The amount billed to the customer for usage during this bill period. This should only include the variable charge for the actual energy usage, and should exclude taxes, account fees, rebates, or other bill adjustments.
• readType(required): string
  Allowed Values: [ "ACTUAL", "ESTIMATED", "SELF_REPORTED", "FORECAST" ]
• start(required): string
  The start of the period. This is an inclusive date/time String in ISO8601 format.
• usage(required): number
  The total energy use for the day, in the chosen fuel type units.

{
    "type":"object",
    "required":[
        "start",
        "end",
        "billDate",
        "usage",
        "readType"
    ],
    "properties":{
        "start":{
            "type":"string",
            "description":"The start of the period. This is an inclusive date/time String in ISO8601 format."
        },
        "end":{
            "type":"string",
            "description":"The end of the period. This is an exclusive date/time String in ISO8601 format."
        },
        "billDate":{
            "type":"string",
            "description":"The end date of meter read period."
        },
        "usage":{
            "type":"number",
            "description":"The total energy use for the day, in the chosen fuel type units."
        },
        "providedCost":{
            "type":"number",
            "description":"The amount billed to the customer for usage during this bill period. This should only include the variable charge for the actual energy usage, and should exclude taxes, account fees, rebates, or other bill adjustments."
        },
        "readType":{
            "$ref":"#/definitions/ReadType"
        }
    }
}

400 Response

Invalid request

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

401 Response

Unauthorized

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

403 Response

Forbidden

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

404 Response

Customer not found

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

500 Response

Internal error

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

503 Response

Service Unavailable

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

Back to Top