API ReferenceIntegrationsKnowledge Base

API Reference

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 perform the following actions using APIs:

You can perform the same operations via the Dashboard as well. Refer to the Dashboard Guide documentation for more details.

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 Authorization#

All Razorpay APIs are authorized using Basic Authorization. Basic authorization requires the following:

  • <YOUR_KEY_ID>
  • <YOUR_KEY_SECRET>

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. Note:
    You have to generate separate API Keys for the test and live modes. No money is deducted from your account in test mode.
  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:

Note:
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.

Entity Structure#

The below JSON is the representation for the invoice entity:

Copy{ "id": "inv_gHQwerty123ggd", "entity": "invoice", "receipt": "BILL13375649", "customer_id": "cust_gHQwerty123ggd", "customer_details": { "name": "Gaurav Kumar", "email": "gaurav.kumar@example.com", "contact": "9123456789", "billing_address": "318 C-Wing, Suyog Co. Housing Society Ltd., T.P.S Road, Vazira, Borivali, West Mumbai, Maharashtra, 400092", "customer_name": null, "customer_email": "gaurav.kumar@example.com", "customer_contact": "9123456789" }, "order_id": "order_gHQwerty123ggd", "line_items": [ { "id": "li_gHQwerty123ggd", "item_id": "item_gHQwerty123gg1", "name": "Book / English August", "description": "Funny story of an IAS officer wanting to be aything other than an IAS.", "amount": 20000, "unit_amount": 20000, "gross_amount": 20000, "tax_amount": 0, "net_amount": 20000, "currency": "INR", "type": "invoice", "tax_inclusive": false, "unit": null, "quantity": 1, "taxes": [] }, { "id": "li_gHQwerty123ggg", "item_id": "item_gHQwerty123gg2", "name": "Book / A Wild Sheep Chase", "description": "A Wild Sheep Chase is the third novel by Japanese author Haruki Murakami.", "amount": 20000, "unit_amount": 20000, "gross_amount": 20000, "tax_amount": 0, "net_amount": 20000, "currency": "INR", "type": "invoice", "tax_inclusive": false, "unit": null, "quantity": 1, "taxes": [] } ], "payment_id": null, "status": "issued", "expire_by": null, "issued_at": 1488446398, "paid_at": null, "cancelled_at": null, "expired_at": null, "sms_status": "pending", "email_status": "pending", "date": 1505937098, "terms": null, "partial_payment": false, "gross_amount": 20000, "tax_amount": 0, "amount": 20000, "amount_paid": 0, "amount_due": 20000, "currency": "INR", "description": null, "notes": [], "comment": null, "short_url": "http://rzp.io/w4ahvtz", "view_less": true, "billing_start": null, "billing_end": null, "type": "invoice", "group_taxes_discounts": false, "user_id": null, "created_at": 1505935715 }

Create an Invoice#

The following API endpoint creates an invoice:

/invoices

Request Body Attributes#

The following table lists out the attributes that should be sent in the request body:

type mandatory

string Must pass type=invoice

customer_id optional

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

customer

Details related to the customer

name mandatory

string Name of the customer

email optional

string email ID of the customer

contact optional

string contact number of the customer

billing_address

Billing address of the customer

line1 mandatory
string
line2 optional
string
city mandatory
string
zipcode mandatory
string
state mandatory
string
country mandatory
string
currency mandatory

Defaults to INR. Click here for a list of supported currencies.

description optional

string

line_items

Description of the line items

item_id optional
string If you are using Items API, you may use an 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.Note:
You can only use items of type invoice while creating an invoice.
name mandatory
string Is required without Item ID.
description optional
string
amount mandatory
integer Is required without item ID.
currency mandatory without _item_id
integer This needs to be same as currency attribute. Defaults to INR. Click here for a list of supported currencies.
quantity optional
integer. Defaults to 1
expire_by optional
epoch/integer
sms_notify optional

string Possible values 0 or 1. Default value is 1

email_notify optional

string Possible values 0 or 1. Default value is 1

date optional

epoch/integer

terms optional

string

notes optional

object

comment optional

string

draft optional

string Possible values 0 or 1. Default value is 1

receipt optional

string

Note:
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. The issued Invoices will be sent as payment links, using which the customer will be able to make payments. You can use Items APIs to create items which you can later use as a template to create line items in an invoice.

Fetch Multiple Invoices#

You can fetch multiple invoices using the following end point:

/invoices

Accepted Query Parameters

  • type
  • payment_id
  • receipt
  • customer_id
  • international
    Note: You can now fetch all the Invoices that have any of the supported international currencies using international=1 as the query parameter in the API request.

Send or Resend Notifications#

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

/invoices/:id/notify_by/:medium

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

Update an Invoice#

To update an invoice via API, use this endpoint:

/invoices/:id

In draft state all the attributes are allowed.

Note:
Invoice update is a patch request and line_items are treated as attributes. So when you send the line_items array, you would be replacing current set of line_items with the new set. Some of the possible scenarios are:


- optionally with updated values of the existing line items
- remove some of the existing line_items



For example, in Sample Request #1 - line_items with id li_00000000000001 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.


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.

Delete an Invoice#

You can delete an invoice which is in the draft state.

/invoices/:id

The response will always be an empty array.

Receiving Notifications via Webhooks#

When the customer pays the amount given in the Invoice, you can enable Webhook to get notified about it. You can subscribe to the events generated for the following states of the Invoice:

Invoice Paid#

Triggered when an Invoice is successfully paid. The sample payload posted for the invoice.paid event is given below:

Copy{ "entity": "event", "event": "invoice.paid", "contains": ["payment", "order", "invoice"], "payload": { "payment": { "entity": { "id": "pay_6koWN7bvxujzxM", "entity": "payment", "amount": 10000, "currency": "INR", "status": "captured", "order_id": "order_6koWN7bvxujzxM", "invoice_id": "inv_6GfX4mcIAdsfDQ", "international": false, "method": "card", "amount_refunded": 0, "refund_status": null, "captured": true, "description": "A Wild Sheep Chase is the third novel by Japanese author Haruki Murakami", "card_id": "card_6koWNAT6LASUqy", "bank": null, "wallet": null, "vpa": null, "email": "gaurav.kumar@example.com", "contact": "9123456780", "notes": { "merchant_order_id": "merchant_reciept_id" }, "fee": 23000, "tax": 3000, "error_code": null, "error_description": null, "created_at": 1479978483 } }, "order": { "entity": { "id": "order_6koWNAT6LASUqy", "entity": "order", "amount": 10000, "currency": "INR", "receipt": "random", "status": "paid", "attempts": 1, "notes": [], "created_at": 1479978483 } }, "invoice": { "entity": { "id": "inv_6koWNAT6LASUqy", "receipt": null, "entity": "invoice", "customer_id": "cust_6koWNAT6LASUqt", "customer_details": { "name": "test", "email": "gaurav.kumar@example.com", "contact": "9123456780", "address": null }, "order_id": "merchant_reciept_id", "line_items": [], "payment_id": "pay_6koWN7bvxujzxM", "status": "paid", "issued_at": null, "paid_at": 1479978484, "sms_status": "sent", "email_status": "sent", "date": null, "terms": null, "amount": 10000, "notes": [], "currency": "INR", "short_url": "http://bit.ly/3he311a", "view_less": true, "type": "link", "created_at": 1479978483 } } }, "created_at": 1479978484 }

Invoice Expired#

Triggered when an invoice gets expired. The sample payload posted for the invoice.expired event is given below:

Copy{ "entity": "event", "event": "invoice.expired", "contains": ["invoice"], "payload": { "invoice":{ "entity":{ "id":"inv_6koWN7bvxujzxM", "entity":"invoice", "receipt":null, "invoice_number":null, "customer_id":"cust_6koWN7bvxujzxM", "customer_details":{ "name":"test", "email":"gaurav.kumar@example.com", "contact":"9123456780", "billing_address":null, }, "order_id":"order_6koWN7bvxujzxM", "payment_id":null, "status":"expired", "expire_by":1505201091, "issued_at":1505088000, "paid_at":null, "cancelled_at":null, "sms_status":"sent", "email_status":"sent", "date":null, "terms":null, "partial_payment":false, "gross_amount":null, "tax_amount":null, "amount":10000, "amount_paid":0, "amount_due":10000, "currency":"INR", "description":null, "notes":[], "comment":null, "short_url":"https://rzp.io/xyzxyzx", "view_less":true, "billing_start":null, "billing_end":null, "type":"invoice", "group_taxes_discounts":false, "user_id":null, "created_at":1505201092 } } }, "created_at":1505201092 }

The webhooks can be enabled from the Dashboard. For more information about enabling the webhook events in the Dashboard, refer the section, Subscribing to Webhook events.