> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Bill Request | BBPS API | Razorpay

> Poll the status and details of a BBPS bill request using Razorpay's Bill Payments API. Returns processing, success or failed status with bill amount and due date on success.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
</div>

Use this endpoint to retrieve the status and details of a bill request created via the [Create a Bill Request](/docs/api/bills/bill-payments/create-bill-request) API. Since bill requests are processed asynchronously, poll this endpoint until the `status` reaches a terminal state of `success` or `failed`. On success, the response contains the bill details, account holder information and any biller-specific metadata required for the next step.

<Info>
  **Polling Recommendation**

  Poll at intervals of 2-5 seconds. The bill retrieval typically completes within 10-30 seconds depending on the biller's response time.
</Info>

<RequestExample>
  ```bash Curl theme={null}
  curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
  -X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM
  ```
</RequestExample>

<ResponseExample>
  ```json Success (bills exist) theme={null}
  {
    "id": "billreq_ERNEungCtXpZqM",
    "entity": "bill_payment.bill_request",
    "status": "success",
    "customer": {
      "id": "rzp_cust_123",
      "name": "Gaurav Kumar",
      "mobile": "919000090000",
      "email": "gaurav.kumar@example.com"
    },
    "biller_id": "biller_001",
    "gateway_biller_id": "TPOW00000MUM01",
    "gateway": "bbps",
    "created_at": 1609459200,
    "account_holder": {
      "account_number": "XXXXXXX",
      "KEY": "VALUE",
      "KEY2": "VALUE2"
    },
    "bills": [
      {
        "bill_number": "820356722187",
        "amount": 1015,
        "currency": "INR",
        "account_holder_name": "Gaurav Kumar",
        "bill_date": 1609459200,
        "due_date": 1609459200,
        "bill_period": "monthly",
        "amount_details": {
          "min_amount_due": 500,
          "current_outstanding_amount": 1015,
          "<KEY>": "<VALUE>"
        }
      }
    ],
    "data": {
      "email": "gaurav.kumar@example.com",
      "KEY2": "VALUE2",
      "KEY3": "VALUE3"
    }
  }
  ```

  ```json Success (bills do not exist) theme={null}
  {
    "id": "billreq_ERNEungCtXpZqM",
    "entity": "bill_payment.bill_request",
    "status": "success",
    "customer": {
      "id": "rzp_cust_123",
      "name": "Gaurav Kumar",
      "mobile": "919000090000",
      "email": "gaurav.kumar@example.com"
    },
    "biller_id": "biller_001",
    "gateway_biller_id": "TPOW00000MUM01",
    "created_at": 1609459200,
    "account_holder": {
      "account_number": "XXXXXXX",
      "KEY": "VALUE",
      "KEY2": "VALUE2"
    },
    "bills": [],
    "data": {
      "email": "gaurav.kumar@example.com",
      "KEY2": "VALUE2",
      "KEY3": "VALUE3"
    },
    "error_code": "BAD_REQUEST_ERROR",
    "error_description": "No bill is currently available for this customer account. The customer may have no outstanding dues or the bill for this cycle has not yet been generated.",
    "error_source": "biller",
    "error_step": "bill_request",
    "error_reason": "no_outstanding_bill"
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "The bill request id is invalid.",
      "source": "business",
      "step": "validation",
      "reason": "invalid_bill_request_id"
    }
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="id" type="string" required>
  Razorpay's bill request id created. For example, `billreq_ERNEungCtXpZqM`.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  Razorpay's bill request id. Store for reference and reconciliation.
</ResponseField>

<ResponseField name="entity" type="string">
  Entity type. Always `bill_payment.bill_request`.
</ResponseField>

<ResponseField name="status" type="string">
  Request status. Possible values:

  * `processing` - The request is in progress. Continue polling.
  * `success` - Bill details retrieved successfully. Proceed to create a payment.
  * `failed` - Bill retrieval failed. See [`error_*`](/docs/errors/bbps/list) fields for details.
</ResponseField>

<ResponseField name="customer" type="object">
  Customer reference details echoed from the request as dynamic key-value pairs. Returned only when sent in the request. Free-form metadata that you can use for your own tracking and reconciliation.
</ResponseField>

<ResponseField name="customer.id" type="string">
  Dynamic key-value pair holding your customer reference. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="customer.name" type="string">
  Dynamic key-value pair holding the customer name. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="customer.mobile" type="string" required>
  Customer mobile number provided at payment create on PA.
</ResponseField>

<ResponseField name="customer.email" type="string">
  Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="biller_id" type="string">
  Razorpay's internal biller id, same as sent in request. Use for reference and reconciliation.
</ResponseField>

<ResponseField name="gateway_biller_id" type="string">
  NPCI biller id. Use for reference and reconciliation.
</ResponseField>

<ResponseField name="gateway" type="string">
  Bill payment gateway used. Default value is `bbps`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Request created timestamp at Razorpay (Unix seconds). Audit trail.
</ResponseField>

<ResponseField name="account_holder" type="object">
  Details of the bill account holder, i.e. the actual user whose bill is being paid. Returned as dynamic key-value pairs defined by the biller's `account_holder_config` (NPCI biller MDM). The keys and values vary by biller. Razorpay does not control either.
</ResponseField>

<ResponseField name="bills" type="array">
  Bill details if a bill is retrieved against the request. Empty array if not available.
</ResponseField>

<ResponseField name="bills[].bill_number" type="string">
  Bill number given from biller. Show bill reference number on UI/UX.
</ResponseField>

<ResponseField name="bills[].amount" type="integer">
  Total bill amount provided by biller in paise. Show the bill amount to be paid by customer.
</ResponseField>

<ResponseField name="bills[].currency" type="string">
  Default to `INR`. Show the currency of the amount in their UI/UX.
</ResponseField>

<ResponseField name="bills[].account_holder_name" type="string">
  Account holder name as per the biller record. Verify against `account_holder` data.
</ResponseField>

<ResponseField name="bills[].bill_date" type="integer">
  Bill generation date from biller (Unix seconds). Show the bill generated date on UI/UX.
</ResponseField>

<ResponseField name="bills[].due_date" type="integer">
  Bill due date from biller (Unix seconds). Show the due date of the bill on UI/UX.
</ResponseField>

<ResponseField name="bills[].bill_period" type="enum">
  Billing frequency. Values: `onetime`, `daily`, `weekly`, `monthly`, `bimonthly`, `quarterly`, `halfyearly`, `yearly`. Show the billing frequency of the bill on UI/UX.
</ResponseField>

<ResponseField name="bills[].amount_details" type="object">
  Amount breakup returned as dynamic key-value pairs defined by the biller (NPCI biller MDM). The keys and values vary by biller category. Razorpay does not control either. Show as part of amount breakup in UI/UX.
</ResponseField>

<ResponseField name="bills[].amount_details.min_amount_due" type="integer">
  Dynamic key-value pair holding the minimum amount due in paise. Returned only when sent by the biller. Varies by biller category.
</ResponseField>

<ResponseField name="bills[].amount_details.current_outstanding_amount" type="integer">
  Dynamic key-value pair holding the current outstanding amount in paise. Returned only when sent by the biller. Varies by biller category.
</ResponseField>

<ResponseField name="data" type="object">
  Dynamic key-value pairs of information sent by biller. Razorpay does not control this. Show biller-specific customer data on receipt.
</ResponseField>

<ResponseField name="error_code" type="string">
  Error code if `status` is `failed` or if no bill is available. For example, `BAD_REQUEST_ERROR`, `GATEWAY_ERROR`.
</ResponseField>

<ResponseField name="error_description" type="string">
  Human-readable error description.
</ResponseField>

<ResponseField name="error_source" type="string">
  Origin of the error. Values: `customer`, `biller`, `gateway`, `business`.
</ResponseField>

<ResponseField name="error_step" type="string">
  Step at which the error occurred. For example, `bill_request`, `validation`.
</ResponseField>

<ResponseField name="error_reason" type="string">
  Programmatic error reason code. Use for error-specific handling logic.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="The bill request id is invalid or not found.">
    **Code:** `400`

    No bill request was found for the provided id.

    **Solution:** Verify the `id` matches the one returned by the Create a Bill Request API.
  </Accordion>

  <Accordion
    title="The API `<key/secret>
` provided is invalid."
  >
    **Code:** `401`

    The API credentials passed in the request differ from the ones generated on the Dashboard.

    **Solution:** Ensure your API key and secret are correct and active.
  </Accordion>
</AccordionGroup>