Introduction

API Reference Guide

API Changelog

API Basics

Authentication & Sandbox Setup

Entity & Metadata

Pagination & Rate Limiting

Best Practices

Glossary

Payments

Orders

Payments

Downtime

Settlements

Instant Settlements

Refunds

Disputes

Documents

Customers

Payment Links

QR Codes

Invoices

Items

Plans

Subscriptions

Add-on

Linked Account

Stakeholder

Product Configuration

Transfers

Smart Collect

Smart Collect With TPV

TPAP Pro

Customer Onboarding

Accounts Management

Payments

Mandates Flow

Bills

About Bills

Bills Entity

Create a Bill

Update a Bill

Delete a Bill

Partners

Account

Product Configuration

Stakeholder

Terms and Conditions

Documents

Webhooks

Payout APIs

Get Started

Account Validation

Composite Account Validation

Contacts

Fund Accounts

Payouts

Payouts to Cards

Payout Composite

Payouts Approval

Payout Idempotency

Payout Links

Payout Wallet - Amazon

Transactions

Api

Payments

Items

Create

API Test Keys

Create an Item

POST
/v1/items

Click to copy

Use this endpoint to create an item with basic details such as name and amount. After an item is created, it appears on the list of created items and in the drop-down menu at the time of invoice creation.

Is this page helpful?

Curl

change language

change language

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
  -H "Content-Type: application/json" \
3
  -X POST https://api.razorpay.com/v1/items \
4
  -d '{
5
        "name":"Book / English August",
6
        "description":"An indian story, Booker prize winner.",
7
        "amount": 20000,
8
        "currency": "INR"
9
      }'

Success

Failure

1
{
2
  "id": "item_JInaSLODeDUQiQ",
3
  "active": true,
4
  "name": "Book / English August",
5
  "description": "An indian story, Booker prize winner.",
6
  "amount": 20000,
7
  "unit_amount": 20000,
8
  "currency": "INR",
9
  "type": "invoice",
10
  "unit": null,
11
  "tax_inclusive": false,
12
  "hsn_code": null,
13
  "sac_code": null,
14
  "tax_rate": null,
15
  "tax_id": null,
16
  "tax_group_id": null,
17
  "created_at": 1649843796
18
}
Request Parameters
name

*

string

Name of the item.

description
string

A brief description about the item.

amount

*

integer

The price of the item. In the case of three decimal currencies, such as KWD, BHD and OMR, to refund a payment of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, to refund a payment of 295, pass the value as 295.

Watch Out!

As per payment guidelines, you should pass the last decimal number as 0 for three decimal currency payments. For example, if you want to refund a customer 99.991 KD for a transaction, you should pass the value for the amount parameter as 99990 and not 99991.

currency

*

string

The currency in which the amount should be charged. Check the list of

supported currencies

.

Handy Tips

Razorpay has added support for zero decimal currencies, such as JPY, and three decimal currencies, such as KWD, BHD, and OMR, allowing businesses to accept international payments in these currencies. Know more about

Currency Conversion

(May 2024).

Response Parameters
id
string

The unique identifier of the item.

active
boolean

Indicates the status of the item. Possible values:

  • true (default): Item is in the active state.
  • false: Item is in the inactive state.

name
string

The name of the item.

description
string

A text description about the item.

amount
integer

The price of the item.

unit_amount
integer

The per unit billing amount for each individual unit.

currency
string

The currency in which the amount should be charged. Check the list of

supported currencies

.

type
string

Here, it must be invoice.

unit
integer

The number of units of the item billed in the invoice.

tax_inclusive
boolean

Indicates whether the base amount includes tax.

  • true: The base amount includes tax.
  • false: The base amount does not include tax. By default, the value is set to false.

hsn_code
integer

The 8-digit code used to classify the product as per the Harmonised System of Nomenclature.

sac_code
integer

The 6-digit code used to classify the service as per the Services Accounting Code.

tax_rate
string

The percentage at which an individual or a corporation is taxed.

tax_id
string

The identification number that gets displayed on invoices issued to the customer.

tax_group_id
string

The identification number for the tax group. A tax group is a collection of taxes that can be applied as a single set of rules.

created_at
integer

Unix timestamp, at which the item was created. For example, 1649843796.

Errors

The API <key/secret> provided is invalid.

Error Status: 4xx

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

  • Different keys for test mode and live modes.
  • Expired API key.

Solution

The currency field is required.

Error Status: 400

The currency field is blank.

Solution

The merchant doesn't have international activated

Error Status: 400

This happens when an international currency code is added.

Solution

The amount must be atleast INR 1.00

Error Status: 400

This happens when the amount added in the amount field is less than INR 1.

Solution

Create an Item

POST
/v1/items

Click to copy

Use this endpoint to create an item with basic details such as name and amount. After an item is created, it appears on the list of created items and in the drop-down menu at the time of invoice creation.

Is this page helpful?

Request Parameters
name

*

string

Name of the item.

description
string

A brief description about the item.

amount

*

integer

The price of the item. In the case of three decimal currencies, such as KWD, BHD and OMR, to refund a payment of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, to refund a payment of 295, pass the value as 295.

Watch Out!

As per payment guidelines, you should pass the last decimal number as 0 for three decimal currency payments. For example, if you want to refund a customer 99.991 KD for a transaction, you should pass the value for the amount parameter as 99990 and not 99991.

currency

*

string

The currency in which the amount should be charged. Check the list of

supported currencies

.

Handy Tips

Razorpay has added support for zero decimal currencies, such as JPY, and three decimal currencies, such as KWD, BHD, and OMR, allowing businesses to accept international payments in these currencies. Know more about

Currency Conversion

(May 2024).

Response Parameters
id
string

The unique identifier of the item.

active
boolean

Indicates the status of the item. Possible values:

  • true (default): Item is in the active state.
  • false: Item is in the inactive state.

name
string

The name of the item.

description
string

A text description about the item.

amount
integer

The price of the item.

unit_amount
integer

The per unit billing amount for each individual unit.

currency
string

The currency in which the amount should be charged. Check the list of

supported currencies

.

type
string

Here, it must be invoice.

unit
integer

The number of units of the item billed in the invoice.

tax_inclusive
boolean

Indicates whether the base amount includes tax.

  • true: The base amount includes tax.
  • false: The base amount does not include tax. By default, the value is set to false.

hsn_code
integer

The 8-digit code used to classify the product as per the Harmonised System of Nomenclature.

sac_code
integer

The 6-digit code used to classify the service as per the Services Accounting Code.

tax_rate
string

The percentage at which an individual or a corporation is taxed.

tax_id
string

The identification number that gets displayed on invoices issued to the customer.

tax_group_id
string

The identification number for the tax group. A tax group is a collection of taxes that can be applied as a single set of rules.

created_at
integer

Unix timestamp, at which the item was created. For example, 1649843796.

Errors

The API <key/secret> provided is invalid.

Error Status: 4xx

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

  • Different keys for test mode and live modes.
  • Expired API key.

Solution

The currency field is required.

Error Status: 400

The currency field is blank.

Solution

The merchant doesn't have international activated

Error Status: 400

This happens when an international currency code is added.

Solution

The amount must be atleast INR 1.00

Error Status: 400

This happens when the amount added in the amount field is less than INR 1.

Solution

Curl

change language

change language

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
  -H "Content-Type: application/json" \
3
  -X POST https://api.razorpay.com/v1/items \
4
  -d '{
5
        "name":"Book / English August",
6
        "description":"An indian story, Booker prize winner.",
7
        "amount": 20000,
8
        "currency": "INR"
9
      }'

Success

Failure

1
{
2
  "id": "item_JInaSLODeDUQiQ",
3
  "active": true,
4
  "name": "Book / English August",
5
  "description": "An indian story, Booker prize winner.",
6
  "amount": 20000,
7
  "unit_amount": 20000,
8
  "currency": "INR",
9
  "type": "invoice",
10
  "unit": null,
11
  "tax_inclusive": false,
12
  "hsn_code": null,
13
  "sac_code": null,
14
  "tax_rate": null,
15
  "tax_id": null,
16
  "tax_group_id": null,
17
  "created_at": 1649843796
18
}