BBPS

About Bills

Api

Bills

Bill Payments

Fetch Biller Plans

API Test Keys

Fetch Biller Plans

GET
/v1/bill_payments/biller_plans

Click to copy

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.

Is this page helpful?

Curl

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-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

Failure

1
{
2
  "entity": "collection",
3
  "count": 2,
4
  "items": [
5
    {
6
      "id": "rzp_plan_1",
7
      "entity": "bill_payment.biller_plan",
8
      "gateway_plan_id": "ZEESPLAN1",
9
      "gateway": "bbps",
10
      "biller_id": "biller_001",
11
      "gateway_biller_id": "TPOW00000MUM01",
12
      "name": "ZEE 5 Premium",
13
      "duration": "1 month",
14
      "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.",
15
      "amount": 12100,
16
      "currency": "INR",
17
      "category": "Premium",
18
      "sub_category": ["1 month", "limited availability"],
19
      "status": "active",
20
      "effective_from": 1609459200,
21
      "effective_to": 1735689600,
22
      "created_at": 1609459200,
23
      "updated_at": 1609459200,
24
      "data": {
25
        "package_name": "Zee 5 premium",
26
        "Package Duration": "1 month",
27
        "<KEY>": "<VALUE>"
28
      }
29
    },
30
    {
31
      "id": "rzp_plan_2",
32
      "entity": "bill_payment.biller_plan",
33
      "gateway_plan_id": "ZEESPLAN2",
34
      "gateway": "bbps",
35
      "biller_id": "biller_001",
36
      "gateway_biller_id": "TPOW00000MUM01",
37
      "name": "ZEE 5 exclusive",
38
      "duration": "3 months",
39
      "description": "All ZEE5 specials for you, shows before telecast. Grab before its gone.",
40
      "amount": 17900,
41
      "currency": "INR",
42
      "category": "Exclusive",
43
      "sub_category": ["specials", "3 months", "limited availability"],
44
      "status": "active",
45
      "effective_from": 1609459200,
46
      "effective_to": 1735689600,
47
      "created_at": 1609459200,
48
      "updated_at": 1609459200,
49
      "data": {
50
        "package_name": "Zee 5 exclusives",
51
        "Package Duration": "3 months"
52
      }
53
    }
54
  ]
55
}
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.

Error Status: 400

biller_id is required.

Solution

Biller does not support plan-based payments.

Error Status: 400

The biller is not configured for prepaid plans.

Solution

The count exceeds the maximum limit.

Error Status: 400

Count exceeds maximum limit of 100.

Solution

Unable to fetch plans from NPCI.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

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

Solution

Fetch Biller Plans

GET
/v1/bill_payments/biller_plans

Click to copy

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.

Is this page helpful?

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.

Error Status: 400

biller_id is required.

Solution

Biller does not support plan-based payments.

Error Status: 400

The biller is not configured for prepaid plans.

Solution

The count exceeds the maximum limit.

Error Status: 400

Count exceeds maximum limit of 100.

Solution

Unable to fetch plans from NPCI.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

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

Solution

Curl

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-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

Failure

1
{
2
  "entity": "collection",
3
  "count": 2,
4
  "items": [
5
    {
6
      "id": "rzp_plan_1",
7
      "entity": "bill_payment.biller_plan",
8
      "gateway_plan_id": "ZEESPLAN1",
9
      "gateway": "bbps",
10
      "biller_id": "biller_001",
11
      "gateway_biller_id": "TPOW00000MUM01",
12
      "name": "ZEE 5 Premium",
13
      "duration": "1 month",
14
      "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.",
15
      "amount": 12100,
16
      "currency": "INR",
17
      "category": "Premium",
18
      "sub_category": ["1 month", "limited availability"],
19
      "status": "active",
20
      "effective_from": 1609459200,
21
      "effective_to": 1735689600,
22
      "created_at": 1609459200,
23
      "updated_at": 1609459200,
24
      "data": {
25
        "package_name": "Zee 5 premium",
26
        "Package Duration": "1 month",
27
        "<KEY>": "<VALUE>"
28
      }
29
    },
30
    {
31
      "id": "rzp_plan_2",
32
      "entity": "bill_payment.biller_plan",
33
      "gateway_plan_id": "ZEESPLAN2",
34
      "gateway": "bbps",
35
      "biller_id": "biller_001",
36
      "gateway_biller_id": "TPOW00000MUM01",
37
      "name": "ZEE 5 exclusive",
38
      "duration": "3 months",
39
      "description": "All ZEE5 specials for you, shows before telecast. Grab before its gone.",
40
      "amount": 17900,
41
      "currency": "INR",
42
      "category": "Exclusive",
43
      "sub_category": ["specials", "3 months", "limited availability"],
44
      "status": "active",
45
      "effective_from": 1609459200,
46
      "effective_to": 1735689600,
47
      "created_at": 1609459200,
48
      "updated_at": 1609459200,
49
      "data": {
50
        "package_name": "Zee 5 exclusives",
51
        "Package Duration": "3 months"
52
      }
53
    }
54
  ]
55
}