Api

Payments

Invoices

Invoices

Create, update, delete, cancel, fetch and send Invoices using Razorpay APIs.

You can use Razorpay Invoices 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 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🔗

The Invoices entity has the following fields:

id

string The unique identifier of the invoice.

entity

string Indicates the type of entity. Here, it is invoice.

type

string Here, it should be invoice.

invoice_number

string Unique number you added for internal reference. The minimum character length is 1 and maximum is 40.

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 Unique identifier of the customer. For example, cust_1Aa00000000004.

name

string Customer's name. Alphanumeric, with period (.), apostrophe (') and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.

email

string The customer's email address. A maximum length of 64 characters. For example, gaurav.kumar@example.com.

contact

string The customer's phone number. A maximum length of 15 characters including country code. For example, +919876543210.

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. Know more about Invoice States. 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. The maximum character length is 2048.

notes

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

short_url

string The short URL that is generated. Share this link with customers to accept payments.

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.

You can create and manage Invoices using APIs or from the Razorpay Dashboard.

Create an Invoice🔗

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. You can use Items APIs to create items which you can later use as a template to create line items in an invoice.
  3. Issue it at a later time with the Issue Invoice API.
  4. You will get a short URL in the response after you issue the invoice to the customer.
  5. Send this URL to the customer to accept payments.

Handy Tips
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

The following endpoint creates an invoice using details such as name, billing_address and shipping_address. If you are using the Customers API, you only need to pass the customer_id.

/invoices

Example 1🔗

Example 2🔗

Request Parameters🔗

type mandatory

string Indicates the type of entity. 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 Customer's name. Alphanumeric, with period (.), apostrophe (') and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.

email optional

string The customer's email address. A maximum length of 64 characters. For example, gaurav.kumar@example.com.

contact optional

string The customer's phone number. A maximum length of 15 characters including country code. For example, +919876543210.

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.

Response Parameters🔗

Descriptions for the response parameters are present in the Invoices Entity parameters table.

Update an Invoice🔗

The following endpoint updates the invoices details.

/invoices/:id

Path Parameter🔗

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

Request Parameters🔗

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.

    Response Parameters🔗

    Descriptions for the response parameters are present in the Invoices Entity parameters table.

    Issue an Invoice🔗

    The following endpoint issues invoices to your customers. Only an invoice in the draft state can be issued.

    /invoices/:id/issue

    Path Parameter🔗

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

    Response Parameters🔗

    Descriptions for the response parameters are present in the Invoices Entity parameters table. The status of the invoice will now be issued and it will have a short_url generated.

    Delete an Invoice🔗

    The following endpoint deletes invoices. You can only delete an invoice that is in the draft state.

    /invoices/:id

    Path Parameter🔗

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

    Response Parameters🔗

    The response will always be an empty array.

    Cancel an Invoice🔗

    The following endpoint cancels an invoice.

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

    Response Parameters🔗

    Descriptions for the response parameters are present in the Invoices Entity parameters table. The status of the invoice will now be cancelled.

    Fetch an Invoice🔗

    The following endpoint retrieves all the details of an invoice.

    /invoices/:id

    Path Parameter🔗

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

    Response Parameters🔗

    Descriptions for the response parameters are present in the Invoices Entity parameters table.

    Fetch Multiple Invoices🔗

    The following endpoint retrieves all the details of multiple invoices.

    /invoices

    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.

    Response Parameters🔗

    Descriptions for the response parameters are present in the Invoices Entity parameters table.

    Send Notifications🔗

    The following endpoint sends notifications with the short URL to the customer via email or SMS.

    /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.
    ×

    ON THIS PAGE