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.

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 the Postman Collection#

  • All Razorpay APIs are authorized using Basic Authorization.
    • Generate API Keys from the Dashboard .
    • 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 added by you for internal reference.

customer_id

string The unique identifier of the customer. You can create customer_id using Customer 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 the customer resides in.
zipcode
string The zipcode linked to the customer address.
state
string The state the customer resides in.
country
string The country the customer resides in.
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 the customer resides in.
zipcode
string The zipcode linked to the customer address.
state
string The state the customer resides in.
country
string The country the customer resides in.
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.

id
string Unique identifier that is generated if a new item has been created on-the-fly during Invoice creation.
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 thelist 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 are:

  • 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, which the Invoice was canceled by you.

expired_at

integer Timestamp, in Unix format, at which the Invoice has 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 item. Default is INR. Refer the list of supported international currencies.

description

string A brief description of the Invoice.

notes

json object Any custom notes added to the Invoice.

short_url

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

type

string Here, it is invoice.

description

string The brief description provided for the Invoice.

date

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

terms

string Any terms to be included in the Invoice.

comment

string Any comments to be added in the Invoice.

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 Customer 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 now create non-GST Invoices using any of these international currencies, using our APIs.

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 the Issue Invoice 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.

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 being created on-the-fly.

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 The brief description provided for 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 Customer 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 the customer resides in.
zipcode mandatory
string The zipcode linked to the customer address.
state mandatory
string The state the customer resides in.
country mandatory
string The country the customer resides in.
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 the customer resides in.
zipcode mandatory
string The zipcode linked to the customer address.
state mandatory
string The state the customer resides in.
country mandatory
string The country the customer resides in.
line_items

Details of the line item that is billed in the Invoice.

item_id conditionally mandatory
string If you are using 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 has not been 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 has not been provided.
currency optional
string The currency associated with the item. Defaults to INR. Refer to the list of supported international currencies.
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.

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 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 and hence the 'line_items' could be updated. In the second request, the Invoice is in the 'issued' state, wherein, only select 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 short_url generated. Also, SMS and email would be sent to customer based on what parameters were sent initially during creation.

The following endpoint can be used to issue an Invoice:

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 must be deleted.

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 retrieved.

Fetch Multiple Invoices#

You can fetch multiple invoices using the following endpoint:

/invoices

Request #1
In this example, details of all the Invoices can be retrieved.

Request #2
In this example, details of 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 entered by you 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 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 Allowed values are:
  • sms
  • email

Response Parameter#

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