API ReferenceIntegrationsKnowledge Base

Invoices

Razorpay APIs lets you quickly create, issue, and cancel invoices for customers on your site/app. These developer-friendly APIs also let you update, delete, and perform other operations on the customer's invoice. Everything that can be done via APIs can also be done on the Dashboard.

Invoices Entity#

The below JSON is the representation for the invoice entity:

type string in: link/ecod/invoice
Mandatory. Must pass type=invoice
currency string
Mandatory. Select the currency from the list.
description string
Optional
customer_id string
Optional. You can pass the customer_id in this field, if you are using Customer API. If not, you can pass the customer object described in the below fields.
customer[name] string
Mandatory, without customer_id.
customer[email] string
Optional
customer[contact] string
Optional
customer[billing_address] string
Mandatory
billing_address[line2] string
Optional
billing_address[city] string
Mandatory
billing_address[zipcode] string
Mandatory
billing_address[state] string
Mandatory
billing_address[country] string
Mandatory
line_items[item_id] string
Optional. If you are using Items API, you may use existing item as a template for line items of invoice. You can still override other details such as name, description by passing these along with item_id. Item will not be updated.
line_items[name] string
Mandatory. without item_id
line_items[description] string
Optional
line_items[amount] integer
Mandatory, without item_id
line_items[currency] integer
Mandatory, without item_id. Only INR is accepted for now. Also, this needs to be same as currency attribute.
line_items[quantity] integer
Optional. Defaults to 1
expire_by epoch/integer
Optional
sms_notify string in: 0/1
Optional. Defaults to 1
email_notify string in: 0/1
Optional. Defaults to 1
date epoch/integer
Optional
terms string
Optional
notes object
Optional
comment string
Optional
draft string in: 0/1
Optional, Defaults to 0

Create an Invoice#

An invoice entity is created for the items ordered on your site/app by a customer. If you are using the customer API, you only need to pass the customer_id. You can also use the customer_id. The following API endpoint creates an invoice:

/invoices

Request Parameters#

The following table describes the required attributes that are sent in request body:

type string
Defines the type of the entity. For Invoices type: "invoice"
currency string
Defines the currency of the payment. Currently we only support INR, currency: "INR"
[customer] name string
Name of the customer.
[billing_address] line1 string
Billing address of the customer
[billing_address] city string
City of the customer billing address
[billing_address] zipcode string
Zipcode of the customer billing address
[billing_address] state string
State of the customer billing address
[billing_address] country string
Country of the customer billing address
[line_items] name string
The name of the item
line_items[amount] integer
The amount of the item
line_items[][currency] integer
Only INR is accepted for now. Also, this needs to be same as currency attribute.

You can create a blank invoice (with no details at all) in draft state, update it with necessary information and then issue it at a later time with this API. Only after the invoice is issued, you will get a short URL. 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.

Update an Invoice#

To update an invoice from the Dashboard, refer to the Update an Invoice Section. To update an invoice via API, use this endpoint:

/invoices/:id

In draft state all the attributes are allowed.

Invoice update is a patch request and line_items are treated as attributes. So when you send line_items array, you would be replacing current set of line_items with the new set. Given that, you may do something like following: keep some (optionally with updated values) of the existing line items (by line_item's id in dictionary with other optional attributes), remove some of the existing line_items (by not having them in new set at all) and add some new line items by passing new dictionary in same line_items array(or list).

For example, in Request #1 - line_items with id li_gHQwerty123gg1 will be patched with the updated name and quantity, a new line_items would be added (the second dictionary in the line_items array) and all other existing would be removed.

Issue an Invoice#

You can issues an invoice in draft state. A short URL or payment link gets created only when the invoice is in issued state. Only then can the customer proceed with the payment.

The following endpoint can be used to issue an invoice:

/invoices/:id/issue

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

Delete an Invoice#

To delete an invoice use this endpoint:

/invoices/:id

An invoice in the draft state can be deleted.

Cancel an Invoice#

To cancel an unpaid Invoice with given ID via API, use this endpoint:

/invoices/:id/cancel

It can only be called on an invoice that is not in the paid state. The response for the API will be the invoice entity, similar to create/update API response, with status attribute's value as cancelled.

Fetch an Invoice#

To search an invoice via API with given ID, use this endpoint:

/invoices/:id

The response for the API will be similar to the entity as detailed here.

Fetch Multiple Invoices#

You can fetch multiple invoices using the following end point:

/invoices

Accepted Query Parameters**#

  • type
  • payment_id
  • receipt
  • customer_id

Send or Resend Notifications#

You can send/resend notifications with the short url to customer via email/sms, using following endpoint:

/invoices/:id/notify_by/:medium

Allowed values for medium URL param is SMS and Email.

Curl