API ReferenceIntegrationsKnowledge Base

Invoices

Razorpay Invoices enables you to send invoices to your customers and accept payments instantly.

The invoice contains information regarding the sale such as the name of the ordered products or services, quantity, billing cycle, price breakup, receipt number and customer information.

You can create, update, cancel and delete invoices using our APIs.

GST and Non-GST Invoices:
Currently, you can only create non-GST Invoices via APIs.

International Currency Support:
You can now create non-GST invoices in any of the supported international currencies using our APIs. You cannot add tax rates for invoices created using international currencies.

API Gateway URL🔗

The Razorpay API Gateway URL is https://api.razorpay.com/v1.

You need to include this before each API endpoint to make API calls.

API Authorisation🔗

All Razorpay APIs are authenticated using Basic Auth. Basic auth requires the following:

  • [YOUR_KEY_ID]
  • [YOUR_KEY_SECRET]

Basic auth expects an Authorization header for each request in the Basic base64token format. Here, base64token is a base64 encoded string of YOUR_KEY_ID:YOUR_KEY_SECRET.

Watch Out
The Authorization header value should strictly adhere to the format mentioned above. Invalid formats will result in authentication failures. Few examples of invalid headers are:

  • BASIC base64token
  • basic base64token
  • Basic "base64token"
  • Basic $base64token

Generate API Key🔗

  1. Log into your Dashboard with appropriate credentials.
  2. Select the mode (Test or Live) for which you want to generate the API key.
    • Test Mode: The test mode is a simulation mode which you can use to test your integration flow. Your customers will not be able to make payments in this mode.
    • Live Mode: When your integration is complete, switch to the live mode and generate live mode API keys. Replace test mode keys with live mode keys in the integration to accept payments from customers.
  3. Navigate to SettingsAPI KeysGenerate Key to generate key for the selected mode.

The Key Id and Key Secret appear in a pop-out window as shown below:

Generate API Keys

Watch Out!

  • After generating the keys from the Dashboard, download and save them securely. If you do not remember your API Keys, you need to re-generate it from the Dashboard and replace it wherever required.
  • Do not share your API Key secret with anyone or on any public platforms. This can pose security threats for your Razorpay account.

Postman Collection🔗

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions to Use Postman Collection🔗

Generate API Keys
  • Add your API Keys in Postman. Selected the required API → Auth → Type = Basic Auth → Username = [Your_Key_ID]; Password = [Your_Key_secret]

  • Some APIs in the collection require data specific to your account such as item_id (Item ID) and inv_id (Invoice ID) as a path parameter.

    • For example, the Fetch Invoice by ID API requires you to add the inv_id as a path parameter.
    • Such parameters are enclosed with {} in the collection. For example, {inv_id}.
    • The API throws an error if these values are incorrect or do not exist in your system.

Invoices Entity🔗

id

string The unique identifier of the invoice.

entity

string Here, it is invoice.

type

string Here, it must be invoice.

invoice_number

string Unique number you added for internal reference.

customer_id

string The unique identifier of the customer. You can create customer_id using the Customers API. Alternatively, you can pass the customer object described in the below fields.

customer_details

Details of the customer.

id

string The unique identifier associated with the customer to whom the invoice has been issued.

name

string The customer's name.

email

string The customer's email address.

contact

string The customer's phone number.

billing_address

Details of the customer's billing address.

id
string The unique identifier generated for the customer's billing address.
type
string The customer address type. Here it is billing_address.
primary
boolean Defines if this is the primary address.
line1
string The first line of the customer's address.
line2
string The second line of the customer's address.
city
string The city.
zipcode
string The zipcode.
state
string The state.
country
string The country.
shipping_address

Details of the customer's shipping address.

id
string The unique identifier generated for the customer's shipping address.
type
string The customer address type. Here it is shipping_address.
primary
boolean Defines if this is the primary address.
line1
string The first line of the customer's address.
line2
string The second line of the customer's address.
city
string The city.
zipcode
string The zipcode.
state
string The state.
country
string The country.
order_id

string The unique identifier of the order associated with the invoice.

line_items

Details of the line item that is billed in the invoice. Maximum of 50 line items.

id
string Unique identifier that is generated if a new item has been created while creating the invoice.
item_id
string Unique identifier of the item generated using Items API that has been billed in the invoice.
name
string The item's name.
description
string A brief description of the item.
amount
integer The price of the item.
currency
string The currency associated with the item. Default is INR. Refer the list of supported international currencies.
type
string Here, it is invoice.
quantity
integer The quantity of the item billed in the invoice. Defaults to 1.
payment_id

string Unique identifier of a payment made against this invoice.

status

string The status of the invoice. Possible values:

  • draft
  • issued
  • partially_paid
  • paid
  • cancelled
  • expired
  • deleted
expire_by

integer Timestamp, in Unix format, at which the invoice will expire.

issued_at

integer Timestamp, in Unix format, at which the invoice was issued to the customer.

paid_at

integer Timestamp, in Unix format, at which the payment was made.

cancelled_at

integer Timestamp, in Unix format, at which the invoice was cancelled.

expired_at

integer Timestamp, in Unix format, at which the invoice expired. sms_status

string The delivery status of the SMS notification for the invoice sent to the customer. Possible values:

  • pending
  • sent
email_status

string The delivery status of the email notification for the invoice sent to the customer. Possible values:

  • pending
  • sent
partial_payment

boolean Indicates whether the customer can make a partial payment on the invoice. Possible values:

  • true - The customer can make partial payments.
  • false (default) - The customer cannot make partial payments.
amount

integer Amount to be paid using the invoice. Must be in the smallest unit of the currency. For example, if the amount to be received from the customer is ₹299.95, pass the value as 29995.

amount_paid

integer Amount paid by the customer against the invoice.

amount_due

integer The remaining amount to be paid by the customer for the issued invoice.

currency

string The currency associated with the invoice. You must mandatorily pass this parameter if accepting international payments. If you have passed currency as a sub-parameter in the line_item object, you must ensure that the same currency is passed in both places. Refer to the list of supported international currencies.

description

string A brief description of the invoice.

notes

object Any custom notes added to the invoice. Maximum of 2048 characters.

short_url

string The short URL that is generated. This is the link that can be shared with the customer to receive payments.

type

string Here, it is invoice.

date

integer Timestamp, in Unix format, that indicates the issue date of the invoice.

terms

string Any terms to be included in the invoice. Maximum of 2048 characters.

comment

string Any comments to be added in the invoice. Maximum of 2048 characters.

Create an Invoice🔗

An invoice entity is created for the items ordered on your website or app by a customer. If you are using the Customers API, you only need to pass the customer_id.

Note:
You cannot create GST compliant invoices using APIs. This means you cannot add the following to the invoice when creating an invoice via APIs:

  • tax rate
  • cess
  • HSN code
  • SAC code

Razorpay supports payments in international currencies. You can create non-GST Invoices using any of these international currencies, using our APIs.

  1. You can create a blank invoice (with no details at all) in draft state.
  2. Update it with necessary information.
  3. Issue it at a later time with the Issue Invoice API.
  4. Only after the invoice is issued, you will get a short URL.
  5. Also, only after the invoice is issued, it can be sent to customers and the corresponding payment can be made against it. You can use Items APIs to create items which you can later use as a template to create line items in an invoice.

The following API endpoint creates an invoice:

/invoices

Request #1
In this example, an invoice is created using the customer and item details. Here, the customer and item are created while creating the invoice.

Request #2
In this example, an invoice is created using existing customer_id and item_id.

Request Parameters🔗

type mandatory

string Here, it is invoice.

description optional

string A brief description of the invoice.

draft optional

string Invoice is created in draft state when value is set to 1.

customer_id optional

string You can pass the customer_id in this field, if you are using the Customers API. If not, you can pass the customer object described in the below fields.

customer

Customer details.

name mandatory

string The customer's name.

email optional

string The customer's email address.

contact optional

string The customer's phone number.

billing_address

The customer's billing address.

line1 mandatory
string The first line of the customer's address.
line2 optional
string The second line of the customer's address.
city mandatory
string The city
zipcode mandatory
string The zipcode
state mandatory
string The state
country mandatory
string The country
shipping_address

The customer's shipping address.

line1 mandatory
string The first line of the customer's address.
line2 optional
string The second line of the customer's address.
city mandatory
string The city
zipcode mandatory
string The zipcode
state mandatory
string The state
country mandatory
string The country
line_items

Details of the line item that is billed in the invoice. Maximum of 50 line items.

item_id conditionally mandatory
string If you are using the Items API, you may use an existing item. You can choose to override details such as name, description by passing these along with item_id. While the invoice will show the updated details, the existing item will not be updated. This parameter is mandatory if you are not going to use any other parameter in the array.
name conditionally mandatory
string The item name. Mandatory if item_id is not provided.
description optional
string A brief description of the item.
amount conditionally mandatory
integer Amount to be paid using the invoice. Must be in the smallest unit of the currency. For example, if the amount to be received from the customer is ₹299.95, pass the value as 29995. Mandatory if item_id is not provided.
currency optional
string The currency associated with the item. Defaults to INR. Refer to the list of supported international currencies. This should match invoice currency.
quantity optional
integer The number of units of the item billed in the invoice. Defaults to 1.
expire_by optional

integer Timestamp, in Unix format, at which the invoice will expire.

sms_notify optional

boolean Defines who handles the SMS notification. Possible values:

  • 0 - you send the notification to the customer.
  • 1 (default) - Razorpay sends the notification to the customer.
email_notify optional

boolean Defines who handles the email notification. Possible values:

  • 0 - you send the notification to the customer.
  • 1 (default) - Razorpay sends the notification to the customer.
partial_payment

boolean Indicates whether the customer can make a partial payment on the invoice. Possible values:

  • true - The customer can make partial payments.
  • false (default) - The customer cannot make partial payments.
currency conditionally mandatory

string The currency associated with the invoice. You must mandatorily pass this parameter if accepting international payments. If you have passed currency as a sub-parameter in the line_item object, you must ensure that the same currency is passed in both places. Refer to the list of supported international currencies.

Update an Invoice🔗

You can update an invoice via API using the endpoint given below:

/invoices/:id

Path Parameter🔗

id mandatory
string The unique identifier of the invoice whose details are to be updated.

Updates allowed as per invoice states

Status

Parameter update allowed

Draft

All parameters can be updated including the line items. You can also add new line items.

Issued

You can update the following parameters:
- partial_payment
- receipt
- comment
- terms
- notes
- expire_by

Cancelled

Only notes can be updated.

Expired

Only notes can be updated.

Partially Paid

Only notes can be updated.

Paid

Only notes can be updated.

In the first request, the invoice is in the 'draft' state, so the 'line_items' can be updated. In the second request, the invoice is in the 'issued' state, wherein, only a few parameter values can be updated.

Issue an Invoice🔗

Only an invoice in the draft state can be issued. Its response is the invoice entity, similar to create/update API response. Its status now would be issued and it will have a short_url generated. Also, SMS and email would be sent to the customer based on what parameters were sent initially during creation.

The following endpoint can be used to issue an invoice:

/invoices/:id/issue

Path Parameter🔗

id mandatory
string The unique identifier of the invoice that needs to be issued.

Delete an Invoice🔗

You can only delete an invoice that is in the draft state. The response will always be an empty array.

/invoices/:id

Path Parameter🔗

id mandatory
string Unique identifier of the invoice that you want to delete.

Cancel an Invoice🔗

You can cancel an unpaid invoice using this endpoint:

/invoices/:id/cancel

Note:
Invoices in paid state cannot be cancelled.

Path Parameter🔗

id mandatory
string The unique identifier of the invoice that needs to be cancelled.

Fetch an Invoice🔗

You can retrieve all the details of an invoice using the following endpoint.

/invoices/:id

Path Parameter🔗

id mandatory
string The unique identifier of the invoice whose details are to be viewed.

Fetch Multiple Invoices🔗

You can fetch multiple invoices using the following endpoint:

/invoices

View All Invoices
In this example, details of all the invoices can be retrieved.

View Invoices Raised for a Customer
In this example, details of the invoices linked to a customer can be retrieved using the customer_id as the query parameter.

Query Parameters🔗

type optional
string Here, it is invoice.
payment_id optional
string The unique identifier of the payment made by the customer against the invoice.
receipt optional
string The unique receipt number that you entered for internal purposes.
customer_id optional
string The unique identifier of the customer. When used, fetches all invoices generated for a customer.

Send Notifications🔗

You can send notifications with the short URL to the customer via email or SMS using the following endpoint:

/invoices/:id/notify_by/:medium

Path Parameters🔗

id mandatory
string The unique identifier of the invoice whose link is to be sent by SMS or email.
medium mandatory
string Possible values:
  • sms
  • email

Response Parameter🔗

success
boolean Indicates whether the notifications were sent successfully. Possible values:
  • true - The notifications were successfully via SMS, email or both.
  • false - The notifications were not sent.
×