> ## 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 Biller Plans | BBPS API | Razorpay

> Retrieve available plans for prepaid BBPS billers such as DTH and recharge providers using Razorpay's Bill Payments API.

<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 catalogue of available prepaid plans (mobile prepaid, DTH packages, broadband plans) for one or more billers. Display recharge options to your customers and enable them to select and purchase plans without leaving your platform. Supports filtering by plan type, amount range and validity period.

<Info>
  **Incremental Sync**

  Pass `updated_since` (Unix timestamp) to fetch only plans updated after a specific time. Use this to keep your local plan catalogue in sync without re-fetching the entire list.
</Info>

<RequestExample>
  ```bash Curl theme={null}
  curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
  -X GET "https://api.razorpay.com/v1/bill_payments/biller_plans?biller_id[]=biller1&biller_id[]=biller2&updated_since=1765009452&count=50&skip=0"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "entity": "collection",
    "count": 2,
    "items": [
      {
        "id": "rzp_plan_1",
        "entity": "bill_payment.biller_plan",
        "gateway_plan_id": "ZEESPLAN1",
        "gateway": "bbps",
        "biller_id": "biller_001",
        "gateway_biller_id": "TPOW00000MUM01",
        "name": "ZEE 5 Premium",
        "duration": "1 month",
        "description": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows, inKids, Live TV, TV shows before telecast. Watch on 5 devices at a time.",
        "amount": 12100,
        "currency": "INR",
        "category": "Premium",
        "sub_category": ["1 month", "limited availability"],
        "status": "active",
        "effective_from": 1609459200,
        "effective_to": 1735689600,
        "created_at": 1609459200,
        "updated_at": 1609459200,
        "data": {
          "package_name": "Zee 5 premium",
          "Package Duration": "1 month",
          "<KEY>": "<VALUE>"
        }
      },
      {
        "id": "rzp_plan_2",
        "entity": "bill_payment.biller_plan",
        "gateway_plan_id": "ZEESPLAN2",
        "gateway": "bbps",
        "biller_id": "biller_001",
        "gateway_biller_id": "TPOW00000MUM01",
        "name": "ZEE 5 exclusive",
        "duration": "3 months",
        "description": "All ZEE5 specials for you, shows before telecast. Grab before its gone.",
        "amount": 17900,
        "currency": "INR",
        "category": "Exclusive",
        "sub_category": ["specials", "3 months", "limited availability"],
        "status": "active",
        "effective_from": 1609459200,
        "effective_to": 1735689600,
        "created_at": 1609459200,
        "updated_at": 1609459200,
        "data": {
          "package_name": "Zee 5 exclusives",
          "Package Duration": "3 months"
        }
      }
    ]
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "Biller does not support plan-based payments.",
      "source": "business",
      "step": "validation",
      "reason": "plans_not_supported"
    }
  }
  ```
</ResponseExample>

## Query Parameters

<ParamField query="biller_id" type="array">
  Razorpay biller identifier(s) (path param). Use to fetch plans for specific billers. For example, `biller_001`.
</ParamField>

<ParamField query="gateway_biller_id" type="array">
  BBPS official biller id(s). Use to fetch plans for specific billers by their NPCI id.
</ParamField>

<ParamField query="plan_id" type="array">
  Razorpay internal plan id(s). Use to fetch updated details of specific plans.
</ParamField>

<ParamField query="updated_since" type="integer">
  Unix timestamp in seconds. Returns only plans updated after this time. Use for incremental sync.
</ParamField>

<ParamField query="skip" type="integer">
  Offset for pagination. Default is `0`.
</ParamField>

<ParamField query="count" type="integer">
  Number of plans per page. Default is `50`. Maximum is `100`.
</ParamField>

## Response Parameters

<ResponseField name="entity" type="string">
  Entity type identifier. Here, `collection`.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of plans in this response.
</ResponseField>

<ResponseField name="items" type="array">
  Array of plan objects.
</ResponseField>

<ResponseField name="items[].id" type="string">
  Razorpay internal plan id assigned to the plan. Use for tracking and analytics.
</ResponseField>

<ResponseField name="items[].entity" type="string">
  Entity type. Always `bill_payment.biller_plan`.
</ResponseField>

<ResponseField name="items[].gateway_plan_id" type="string">
  NPCI-provided plan id. Mandatory to send in bill request for plan validation.
</ResponseField>

<ResponseField name="items[].gateway" type="string">
  Payment gateway. Defaults to `bbps`.
</ResponseField>

<ResponseField name="items[].biller_id" type="string">
  Razorpay biller id reference. Use for internal mapping.
</ResponseField>

<ResponseField name="items[].gateway_biller_id" type="string">
  NPCI biller id. Use to verify the plan matches the selected biller.
</ResponseField>

<ResponseField name="items[].name" type="string">
  Plan name given by the biller. Show to the customer on the UI.
</ResponseField>

<ResponseField name="items[].duration" type="string">
  Plan duration given by the biller. Show to the customer on the UI.
</ResponseField>

<ResponseField name="items[].description" type="string">
  Plan details to show to the customer on the UI.
</ResponseField>

<ResponseField name="items[].amount" type="integer">
  Plan price in paise. Display as `₹{amount/100}` on the UI. Payment uses this exact amount and is non-editable by the customer.
</ResponseField>

<ResponseField name="items[].currency" type="string">
  ISO currency code. Always `INR` for BBPS.
</ResponseField>

<ResponseField name="items[].category" type="string">
  Primary plan category. Use for UI grouping. For example, `Premium`, `Combo`, `Data`, `Voice`.
</ResponseField>

<ResponseField name="items[].sub_category" type="array">
  Plan sub-type or variant. Can be part of multiple sub-categories. Use to filter by duration or plan type.
</ResponseField>

<ResponseField name="items[].status" type="enum">
  Plan availability status. Values: `active`, `deactivated`. Show only active plans on the UI.
</ResponseField>

<ResponseField name="items[].effective_from" type="integer">
  Plan validity start date (Unix seconds). Show only if `current_date >= effective_from`.
</ResponseField>

<ResponseField name="items[].effective_to" type="integer">
  Plan validity end date (Unix seconds). Hide if `current_date > effective_to`.
</ResponseField>

<ResponseField name="items[].created_at" type="integer">
  Plan creation timestamp (Unix seconds). Use to inform merchants when the plan was created in Razorpay's database.
</ResponseField>

<ResponseField name="items[].updated_at" type="integer">
  Last update timestamp (Unix seconds). Use to inform merchants when the plan was last updated in Razorpay's database.
</ResponseField>

<ResponseField name="items[].data" type="object">
  Dynamic key-value pairs from biller. Display additional plan info such as `package_name`, `Package Duration`.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="The `biller_id` is missing or invalid.">
    **Code:** `400`

    `biller_id` is required.

    **Solution:** Pass at least one valid `biller_id` returned by the Fetch Billers API.
  </Accordion>

  <Accordion title="Biller does not support plan-based payments.">
    **Code:** `400`

    The biller is not configured for prepaid plans.

    **Solution:** Check the biller's `bill_request_config.plan_fetch_required` value before calling this API.
  </Accordion>

  <Accordion title="The `count` exceeds the maximum limit.">
    **Code:** `400`

    Count exceeds maximum limit of 100.

    **Solution:** Pass a `count` value between 1 and 100.
  </Accordion>

  <Accordion title="Unable to fetch plans from NPCI.">
    **Code:** `502`

    NPCI did not respond within the timeout window.

    **Solution:** Retry the request after a short interval.
  </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>