Upgraded docs version is here ✨

Your documentation experience is getting an upgrade. Check it out now!

Go To Beta

Docs upgrade is here. Check it out!

Go To Beta
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.

You can try out our APIs on the Razorpay Postman Public Workspace.

Run in Postman

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. Know about 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. Know about 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 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. Know about 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. Know about 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.

The following table displays ths 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

    Handy Tips
    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.
    ‹›
    ×