---
updatedAt: 2026-05-27T19:28:36.000Z
agentTools:
  projectIndex: https://docs.bayou.energy/llms.txt
---

# Get Bill by ID

Retrieves a specific utility bill

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "version": "2.0",
    "title": "Bayou Energy API Reference",
    "x-logo": {
      "url": "https://images.squarespace-cdn.com/content/v1/6193d0f96f0d901cf36109c2/fdce87d5-4ac6-4b5e-a16d-29bd1228edda/BayouEnergy_final-02.png?format=1500w",
      "altText": "Bayou Energy"
    },
    "description": "# Introduction\nThis is the documentation page for Bayou Energy's Utility Data API. This API allows you to manage your connected utility accounts and retrieve utility data for those accounts. Learn more about Bayou Energy at [www.bayou.energy](https://bayou.energy).\n\n# Authentication\nWe use API keys to authenticate requests. You can find your API keys in the [Bayou Dashboard](https://bayou.energy/dashboard).\nAuthentication is provided through HTTP Basic Authentication. Use your API key as the username value in the Basic Authentication scheme. The password value does not need to be filled.\n\n# Utility support\nThe list of supported utilities with support details for each specific utility, as well as their API codes, can be found on our [Utility Support documentation page](https://docs.bayou.energy/reference/utility-support).\n\nIn addition to those utilities, you can also use Speculoos Power (code: `speculoos_power`), which is a fictional utility, to be used for testing purposes only.\n\n# External IDs\nTo avoid the need to add a new field in your database as part of your Bayou implementation, all API models come with an `external_id` field that can be used to save your identifier.\nThe `external_id` can be used to retrieve, update or delete any object and can be a string of any format.\n\nIf the object is created in your environment, just pass this identifier as an argument when you create it using Bayou's API. Objects created within Bayou's environment can be updated using the Bayou identifier to attach your `external_id` to them.\n\nThe use of external IDs is totally optional.\n"
  },
  "servers": [
    {
      "url": "https://bayou.energy/api/v2",
      "description": "Bayou's v2 APIs"
    }
  ],
  "paths": {
    "/bills/{id}": {
      "get": {
        "summary": "Get Bill by ID",
        "description": "Retrieves a specific utility bill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "example": 123,
            "required": true,
            "description": "Can be either Bayou's numeric ID or your own [identifier](https://docs.bayou.energy/reference/external-ids) for this bill preceded with `external_id:`"
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the utility bill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "bill_id_invalid": {
                    "$ref": "#/components/examples/bill_id_invalid"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BillToBeUpdated": {
        "type": "object",
        "properties": {
          "external_id": {
            "type": "string",
            "nullable": true,
            "example": "BILL_123",
            "description": "Your own [identifier](https://docs.bayou.energy/reference/external-ids) for this bill (this field must be unique)"
          }
        }
      },
      "Bill": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BillToBeUpdated"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 1234,
                "description": "The ID of this bill"
              },
              "status": {
                "type": "string",
                "example": "unlocked",
                "enum": [
                  "not_supported",
                  "unparsed",
                  "locked",
                  "partially_unlocked",
                  "unlocked_for_gas",
                  "unlocked_for_electric",
                  "unlocked"
                ],
                "description": "The current status for this bill"
              },
              "customer_id": {
                "type": "integer",
                "example": 12345,
                "description": "The ID of the customer for which this bill was issued"
              },
              "customer_external_id": {
                "type": "string",
                "example": "MSCOTT123",
                "description": "Your own [identifier](https://docs.bayou.energy/reference/external-ids) for the customer for which this bill was issued"
              },
              "billed_on": {
                "type": "string",
                "format": "date",
                "example": "2022-08-01",
                "description": "The date this bill was issued by the utility"
              },
              "utility": {
                "type": "string",
                "example": "con_edison",
                "description": "The utility company that issued this bill. See [Utility support](https://docs.bayou.energy/reference/utility-support) for more information"
              },
              "account_number": {
                "type": "string",
                "example": 123456,
                "description": "The utility account number as displayed on the bill"
              },
              "outstanding_balance": {
                "type": "integer",
                "example": 1200,
                "description": "Remaining balance from the previous billing cycle"
              },
              "billing_period_from": {
                "type": "string",
                "format": "date",
                "example": "2022-07-01",
                "description": "The beginning of the billing period this bill covers"
              },
              "billing_period_to": {
                "type": "string",
                "format": "date",
                "example": "2022-07-31",
                "description": "The end of the billing period this bill covers"
              },
              "electricity_consumption": {
                "description": "Quantity of electricity used this billing cycle, in watt-hours",
                "type": "integer",
                "example": 900
              },
              "electricity_amount": {
                "description": "The amount for all electricity-related charges on the bill, in cents",
                "type": "integer",
                "example": 9060
              },
              "delivery_charge": {
                "description": "Bill electricity delivery charge amount, in cents",
                "type": "integer",
                "example": 5060
              },
              "supply_charge": {
                "description": "Bill electricity supply charge amount, in cents",
                "type": "integer",
                "example": 4000
              },
              "community_solar_bill_credit": {
                "description": "The community solar credit for this bill, in cents",
                "type": "integer",
                "example": -6440
              },
              "gas_consumption_unit": {
                "description": "Unit used for describing all quantities of gas for this bill and its meters. We report gas in the unit the utility prints on the bill rather than converting it, so this can be therms, ccf or mcf depending on the utility",
                "type": "string",
                "example": "therms"
              },
              "gas_consumption": {
                "description": "Quantity of gas used this billing cycle, in the unit given by gas_consumption_unit. Returned as a decimal string with three decimal places (for example \"90.000\"), not a JSON number.",
                "type": "string",
                "example": "90.000"
              },
              "gas_amount": {
                "description": "The amount for all gas-related charges on the bill, in cents",
                "type": "integer",
                "example": 2940
              },
              "total_amount": {
                "description": "The total amount for the bill, including gas, in cents",
                "type": "integer",
                "example": 12000
              },
              "meters": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "example": "XYZ12345",
                      "description": "The ID of this meter"
                    },
                    "status": {
                      "type": "string",
                      "example": "unlocked",
                      "enum": [
                        "locked",
                        "unlocked"
                      ],
                      "description": "The current status for this meter"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "gas",
                        "electric"
                      ],
                      "description": "The type of this meter",
                      "example": "gas"
                    },
                    "billing_period_from": {
                      "type": "string",
                      "format": "date",
                      "example": "2022-07-01",
                      "description": "The start of the billing period for this meter"
                    },
                    "billing_period_to": {
                      "type": "string",
                      "format": "date",
                      "example": "2022-07-31",
                      "description": "The end of the billing period for this meter"
                    },
                    "consumption": {
                      "type": "number",
                      "example": 90,
                      "description": "The consumption of this meter, in watt-hours (a whole number) for electricity meters or, for gas meters, the unit given by gas_consumption_unit (which can be fractional)"
                    },
                    "address": {
                      "type": "object",
                      "properties": {
                        "line_1": {
                          "type": "string",
                          "example": "123 Main St",
                          "description": "The full street address for this meter"
                        },
                        "line_2": {
                          "type": "string",
                          "example": "Apt 1",
                          "description": "The second line of the street address for this meter"
                        },
                        "city": {
                          "type": "string",
                          "example": "New York",
                          "description": "The city for this meter"
                        },
                        "state": {
                          "type": "string",
                          "example": "NY",
                          "description": "The state for this meter"
                        },
                        "postal_code": {
                          "type": "string",
                          "example": 10001,
                          "description": "The zip code for this meter"
                        },
                        "postal_code_suffix": {
                          "type": "string",
                          "example": 1234,
                          "description": "The zip code suffix for this meter"
                        },
                        "country": {
                          "type": "string",
                          "example": "US",
                          "description": "The country for this meter"
                        }
                      }
                    },
                    "tariff": {
                      "type": "string",
                      "example": "123 Residential",
                      "description": "The tariff name for this meter"
                    },
                    "additional_attributes": {
                      "type": "object",
                      "description": "Additional attributes for this meter",
                      "properties": {
                        "gas_choice_id": {
                          "type": "string",
                          "example": 123456789,
                          "description": "The gas choice id for a meter, if provided"
                        }
                      }
                    }
                  },
                  "example": [
                    {
                      "id": "XYZ12345",
                      "status": "unlocked",
                      "type": "gas",
                      "billing_period_from": "2022-07-01",
                      "billing_period_to": "2022-07-31",
                      "consumption": 90,
                      "address": {
                        "line_1": "123 Main St",
                        "line_2": "Apt 1",
                        "city": "New York",
                        "state": "NY",
                        "postal_code": 10001,
                        "postal_code_suffix": 1234,
                        "country": "US"
                      },
                      "tariff": "123 Residential",
                      "additional_attributes": {
                        "gas_choice_id": 123456789
                      }
                    },
                    {
                      "id": "XYZ98765",
                      "status": "unlocked",
                      "type": "electric",
                      "billing_period_from": "2022-07-01",
                      "billing_period_to": "2022-07-31",
                      "consumption": 900,
                      "address": {
                        "line_1": "123 Main St",
                        "line_2": "Apt 1",
                        "city": "New York",
                        "state": "NY",
                        "postal_code": 10001,
                        "postal_code_suffix": 1234,
                        "country": "US"
                      },
                      "tariff": "456 Residential",
                      "additional_attributes": {
                        "electric_choice_id": 987654321
                      }
                    }
                  ]
                }
              },
              "file_url": {
                "type": "string",
                "format": "url",
                "example": "https://private.bayou.energy/bills/12345.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=XYZ&X-Amz-Date=20220701T000000Z&X-Amz-Expires=1800&X-Amz-Signature=ABCEF0123456&X-Amz-SignedHeaders=host",
                "description": "The URL at which the PDF for this bill can be fetched (valid for 15 minutes)"
              }
            }
          }
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_type": {
            "type": "string",
            "description": "The type of error"
          },
          "error_code": {
            "type": "string",
            "description": "The error code"
          },
          "error_message": {
            "type": "string",
            "description": "The error message"
          },
          "docs_url": {
            "type": "string",
            "description": "A link to documentation providing more details about the error"
          }
        }
      }
    },
    "examples": {
      "bill_id_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "bill_id_invalid",
          "error_message": "The bill_id you provided in the request does not exist.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#bill_id_invalid"
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "Bills",
      "description": "The following section defines requests that allow you to manage the utility bills of your customer accounts."
    }
  ]
}
```