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.

GET /v1/bill_payments/biller_plans

Curl

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"

Success

{
  "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"
      }
    }
  ]
}

Available in🇮🇳 India

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.

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.

Curl

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"

Success

{
  "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"
      }
    }
  ]
}

Query Parameters

biller_id · array

Razorpay biller identifier(s) (path param). Use to fetch plans for specific billers. For example, biller_001.

gateway_biller_id · array

BBPS official biller id(s). Use to fetch plans for specific billers by their NPCI id.

plan_id · array

Razorpay internal plan id(s). Use to fetch updated details of specific plans.

updated_since · integer

Unix timestamp in seconds. Returns only plans updated after this time. Use for incremental sync.

skip · integer

Offset for pagination. Default is 0.

count · integer

Number of plans per page. Default is 50. Maximum is 100.

Response Parameters

entity · string

Entity type identifier. Here, collection.

count · integer

Number of plans in this response.

items · array

Array of plan objects.

items[].id · string

Razorpay internal plan id assigned to the plan. Use for tracking and analytics.

items[].entity · string

Entity type. Always bill_payment.biller_plan.

items[].gateway_plan_id · string

NPCI-provided plan id. Mandatory to send in bill request for plan validation.

items[].gateway · string

Payment gateway. Defaults to bbps.

items[].biller_id · string

Razorpay biller id reference. Use for internal mapping.

items[].gateway_biller_id · string

NPCI biller id. Use to verify the plan matches the selected biller.

items[].name · string

Plan name given by the biller. Show to the customer on the UI.

items[].duration · string

Plan duration given by the biller. Show to the customer on the UI.

items[].description · string

Plan details to show to the customer on the UI.

items[].amount · integer

Plan price in paise. Display as ₹{amount/100} on the UI. Payment uses this exact amount and is non-editable by the customer.

items[].currency · string

ISO currency code. Always INR for BBPS.

items[].category · string

Primary plan category. Use for UI grouping. For example, Premium, Combo, Data, Voice.

items[].sub_category · array

Plan sub-type or variant. Can be part of multiple sub-categories. Use to filter by duration or plan type.

items[].status · enum

Plan availability status. Values: active, deactivated. Show only active plans on the UI.

items[].effective_from · integer

Plan validity start date (Unix seconds). Show only if current_date >= effective_from.

items[].effective_to · integer

Plan validity end date (Unix seconds). Hide if current_date > effective_to.

items[].created_at · integer

Plan creation timestamp (Unix seconds). Use to inform merchants when the plan was created in Razorpay’s database.

items[].updated_at · integer

Last update timestamp (Unix seconds). Use to inform merchants when the plan was last updated in Razorpay’s database.

items[].data · object

Dynamic key-value pairs from biller. Display additional plan info such as package_name, Package Duration.

Errors

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.

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.

The `count` exceeds the maximum limit.

Code: 400

Count exceeds maximum limit of 100.

Solution: Pass a count value between 1 and 100.

Unable to fetch plans from NPCI.

Code: 502

NPCI did not respond within the timeout window.

Solution: Retry the request after a short interval.

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.