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

1curl -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

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

1curl -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}