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

# Unlock Bill (entirely or partially) by ID

Unlocks a specific utility bill, entirely or partially, by specifying its ID and optional filters on meters to unlock

# 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}/unlock": {
      "post": {
        "summary": "Unlock Bill (entirely or partially) by ID",
        "description": "Unlocks a specific utility bill, entirely or partially, by specifying its ID and optional filters on meters to unlock",
        "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:`"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "meter_id": {
                    "type": "string",
                    "example": "XYZ12345",
                    "description": "Filter to unlock the bill for a specific meter ID. If not provided, no meter ID filter is applied."
                  },
                  "billing_period_from": {
                    "type": "string",
                    "format": "date",
                    "example": "2022-07-01",
                    "description": "Filter to unlock the bill for meters with a billing period starting on or after this date. If not provided, no start date filter is applied."
                  },
                  "billing_period_to": {
                    "type": "string",
                    "format": "date",
                    "example": "2022-07-31",
                    "description": "Filter to unlock the bill for meters with a billing period ending on or before this date. If not provided, no end date filter is applied."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "gas",
                      "electric"
                    ],
                    "example": "gas",
                    "description": "Filter to unlock the bill for meters of this type. If not provided, no meter type filter is applied."
                  },
                  "additional_attributes": {
                    "type": "object",
                    "description": "Filter to unlock the bill for meters with these additional attributes. If not provided, no additional attribute filter is applied."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The utility bill was unlocked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "details": {
                      "type": "string",
                      "example": "Bill was unlocked"
                    },
                    "bill": {
                      "$ref": "#/components/schemas/Bill"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unlock_billing_period_from_format_invalid": {
                    "$ref": "#/components/examples/unlock_billing_period_from_format_invalid"
                  },
                  "unlock_billing_period_to_format_invalid": {
                    "$ref": "#/components/examples/unlock_billing_period_to_format_invalid"
                  },
                  "unlock_meter_type_invalid": {
                    "$ref": "#/components/examples/unlock_meter_type_invalid"
                  },
                  "unlock_additional_attributes_format_invalid": {
                    "$ref": "#/components/examples/unlock_additional_attributes_format_invalid"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "bill_id_invalid": {
                    "$ref": "#/components/examples/bill_id_invalid"
                  },
                  "external_id_invalid": {
                    "$ref": "#/components/examples/external_id_invalid"
                  },
                  "unlock_meter_id_invalid": {
                    "$ref": "#/components/examples/unlock_meter_id_invalid"
                  },
                  "unlock_additional_attributes_invalid": {
                    "$ref": "#/components/examples/unlock_additional_attributes_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"
        }
      },
      "external_id_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "external_id_invalid",
          "error_message": "The external_id you provided in the request does not exist.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#external_id_invalid"
        }
      },
      "unlock_meter_id_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_meter_id_invalid",
          "error_message": "The meter_id you provided in the request does not exist for this bill.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_meter_id_invalid"
        }
      },
      "unlock_billing_period_from_format_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_billing_period_from_format_invalid",
          "error_message": "The billing_period_from you provided in the request is not a valid date. An example of a valid format is 2022-11-01.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_billing_period_from_format_invalid"
        }
      },
      "unlock_billing_period_to_format_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_billing_period_to_format_invalid",
          "error_message": "The billing_period_to you provided in the request is not a valid date. An example of a valid format is 2022-11-01.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_billing_period_to_format_invalid"
        }
      },
      "unlock_meter_type_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_meter_type_invalid",
          "error_message": "The meter type you provided in the request does not exist for this bill.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_meter_type_invalid"
        }
      },
      "unlock_additional_attributes_format_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_additional_attributes_format_invalid",
          "error_message": "The additional attributes you provided in the request is not a valid JSON object.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_additional_attributes_format_invalid"
        }
      },
      "unlock_additional_attributes_invalid": {
        "value": {
          "error_type": "invalid_request",
          "error_code": "unlock_additional_attributes_invalid",
          "error_message": "The additional attributes you provided in the request do not exist for this bill.",
          "docs_url": "https://docs.bayou.energy/docs/error-codes#unlock_additional_attributes_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."
    }
  ]
}
```