Introduction

API Reference Guide

Understand Razorpay APIs

Authentication

Sandbox Setup

Install CLI

Best Practices

Glossary

Payments

Orders

Payments

Downtime

Settlements

Refunds

Customers

Payment Links

Subscriptions

Api

Payments

Invoices

Create With Customer Id

API Test Keys

Create an Invoice With Customer ID

POST
/v1/invoices

Click to copy

Use this endpoint to create an invoice by passing the customer_id.

Is this page helpful?

Curl

change language

change language

1
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET>
2
-X POST https://api.razorpay.com/v1/invoices \
3
-H 'Content-type: application/json' \
4
-d '{
5
    "type": "invoice",
6
    "date": 1760714528,
7
    "customer_id": "cust_HOQzpsovChhcpl",
8
    "line_items": [
9
        {
10
            "item_id": "item_K6g5L6X43dXjEA"
11
        }
12
    ]
13
}'

Success

Failure

1
{
2
  "id": "inv_K6g5bviu09mXo1",
3
  "entity": "invoice",
4
  "receipt": null,
5
  "invoice_number": null,
6
  "customer_id": "cust_HOQzpsovChhcpl",
7
  "customer_details": {
8
    "id": "cust_HOQzpsovChhcpl",
9
    "name": null,
10
    "email": "alex.lim@example.com",
11
    "contact": "+6591119111",
12
    "gstin": null,
13
    "billing_address": null,
14
    "shipping_address": null,
15
    "customer_name": null,
16
    "customer_email": "alex.lim@example.com",
17
    "customer_contact": "+6591119111"
18
  },
19
  "order_id": "order_K6g5bxSIwYIXJS",
20
  "line_items": [
21
    {
22
      "id": "li_K6g5bwLZuBmb1Q",
23
      "item_id": "item_K6g5L6X43dXjEA",
24
      "ref_id": null,
25
      "ref_type": null,
26
      "name": "Cloth",
27
      "description": "Cotton Cloth",
28
      "amount": 1200,
29
      "unit_amount": 1200,
30
      "gross_amount": 1200,
31
      "tax_amount": 0,
32
      "taxable_amount": 1200,
33
      "net_amount": 1200,
34
      "currency": "",
35
      "type": "invoice",
36
      "tax_inclusive": false,
37
      "hsn_code": null,
38
      "sac_code": null,
39
      "tax_rate": null,
40
      "unit": null,
41
      "quantity": 1,
42
      "taxes": []
43
    }
44
  ],
45
  "payment_id": null,
46
  "status": "issued",
47
  "expire_by": null,
48
  "issued_at": 1660734398,
49
  "paid_at": null,
50
  "cancelled_at": null,
51
  "expired_at": null,
52
  "sms_status": "pending",
53
  "email_status": "pending",
54
  "date": 1760714528,
55
  "terms": null,
56
  "partial_payment": false,
57
  "gross_amount": 1200,
58
  "tax_amount": 0,
59
  "taxable_amount": 1200,
60
  "amount": 1200,
61
  "amount_paid": 0,
62
  "amount_due": 1200,
63
  "currency": "",
64
  "currency_symbol": "<currency_symbol>",
65
  "description": null,
66
  "notes": [],
67
  "comment": null,
68
  "short_url": "https://rzp.io/i/ksYThDL",
69
  "view_less": true,
70
  "billing_start": null,
71
  "billing_end": null,
72
  "type": "invoice",
73
  "group_taxes_discounts": false,
74
  "created_at": 1660734398
75
}
Request Parameters
type

*

string

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

description
string

A brief description of the invoice.

draft
string

Invoice is created in draft state when value is set to 1.

customer_id

*

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
object

Customer details.

Show child parameters (5)

line_items
object

Details of the line item that is billed in the invoice. Maximum of 50 line items.

Show child parameters (6)

expire_by
integer

Timestamp, in Unix format, at which the invoice will expire.

sms_notify
boolean

Defines who handles the SMS notification. Possible values:

  • true (default): Razorpay sends the notification to the customer.
  • false: You send the notification to the customer.

email_notify
boolean

Defines who handles the email notification. Possible values:

  • true (default): Razorpay sends the notification to the customer.
  • false: You send 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
string

The currency associated with the invoice. Possible value: SGD.

notes
string

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

Response Parameters
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
object

Details of the customer.

Show child parameters (6)

order_id
string

The unique identifier of the order associated with the invoice.

line_items
object

Details of the line item that is billed in the invoice. Maximum of 50 line items.

Show child parameters (8)

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 S$300, pass the value as 30000.

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. Possible value: SGD.

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.

Errors

The API <key/secret> provided is invalid.

Error Status: 4xx

The API key or secret are not entered or an invalid API key is used.

Solution

customer is required.

Error Status: 400

An invoice is issued without adding customer details.

Solution

Currency of all items should be the same as of the invoice.

Error Status: 400

There is a difference in currency entered between line_items and invoice currency.

Solution

expire_by should be at least 15 minutes after current time.

Error Status: 400

The expiry date is before or within 15 minutes of the current time

Solution

line_items is required.

Error Status: 400

A mandatory field is empty.

Solution

Not a valid type.

Error Status: 400

The value passed for type is not one of the supported types. The API echoes the rejected value, for example Not a valid type: invoiceee.

Solution

The amount must be at least INR 1.00.

Error Status: 400

A line-item amount is below the per-currency minimum (100 paise / ₹1.00 for INR). Also returned for zero or negative line-item amounts.

Solution

The amount must be an integer.

Error Status: 400

A non-integer value (for example a decimal like 100.5 or a string like "abc") was passed for a line_items[].amount.

Solution

The quantity must be at least 1.

Error Status: 400

A line-item quantity was passed as 0 or a negative value.

Solution

The email must be a valid email address.

Error Status: 400

The value passed for customer.email is not in a valid email format.

Solution

Contact number contains invalid characters, only digits and + symbol are allowed.

Error Status: 400

The customer.contact value contains characters other than digits and the + symbol.

Solution

The partial payment field must be true or false.

Error Status: 400

A non-boolean value was passed for partial_payment.

Solution

{any extra field} is/are not required and should not be sent.

Error Status: 400

The request body contains fields that are not part of the Invoices API schema.

Solution

Invoices disabled because fee bearer is customer.

Error Status: 400

Your account has the customer fee bearer model enabled, which is not compatible with invoice creation.

Solution

Item cannot be used as it is inactive.

Error Status: 400

A line_items[].item_id passed in the request refers to an item that has been marked inactive.

Solution

The merchant doesn't have international activated.

Error Status: 400

The currency passed is different from your account's default currency, but international payments are not enabled on your account.

Solution

Currency is not supported.

Error Status: 400

The currency value is not a recognised ISO-4217 currency code or is outside the list supported by Razorpay.

Solution

Invoice amount exceeds maximum payment amount allowed.

Error Status: 400

The total invoice amount (sum of line_items[].amount * quantity) exceeds the per-payment maximum configured for your account.

Solution

expire_by should be at least 15 minutes after current time.

Error Status: 400

The expire_by value is in the past or less than 15 minutes from the current server time.

Solution

Request failed. Please try after sometime.

Error Status: 429

You have exceeded the daily rate limit for invoice creation. This per-day rate limit applies to test-mode accounts and unregistered live-mode accounts. In test mode the limit is 300 invoices/day; in live mode for unregistered businesses it is 10,000 invoices/day. Registered live-mode accounts are not subject to this limit.

Solution

Create an Invoice With Customer ID

POST
/v1/invoices

Click to copy

Use this endpoint to create an invoice by passing the customer_id.

Is this page helpful?

Request Parameters
type

*

string

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

description
string

A brief description of the invoice.

draft
string

Invoice is created in draft state when value is set to 1.

customer_id

*

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
object

Customer details.

Show child parameters (5)

line_items
object

Details of the line item that is billed in the invoice. Maximum of 50 line items.

Show child parameters (6)

expire_by
integer

Timestamp, in Unix format, at which the invoice will expire.

sms_notify
boolean

Defines who handles the SMS notification. Possible values:

  • true (default): Razorpay sends the notification to the customer.
  • false: You send the notification to the customer.

email_notify
boolean

Defines who handles the email notification. Possible values:

  • true (default): Razorpay sends the notification to the customer.
  • false: You send 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
string

The currency associated with the invoice. Possible value: SGD.

notes
string

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

Response Parameters
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
object

Details of the customer.

Show child parameters (6)

order_id
string

The unique identifier of the order associated with the invoice.

line_items
object

Details of the line item that is billed in the invoice. Maximum of 50 line items.

Show child parameters (8)

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 S$300, pass the value as 30000.

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. Possible value: SGD.

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.

Errors

The API <key/secret> provided is invalid.

Error Status: 4xx

The API key or secret are not entered or an invalid API key is used.

Solution

customer is required.

Error Status: 400

An invoice is issued without adding customer details.

Solution

Currency of all items should be the same as of the invoice.

Error Status: 400

There is a difference in currency entered between line_items and invoice currency.

Solution

expire_by should be at least 15 minutes after current time.

Error Status: 400

The expiry date is before or within 15 minutes of the current time

Solution

line_items is required.

Error Status: 400

A mandatory field is empty.

Solution

Not a valid type.

Error Status: 400

The value passed for type is not one of the supported types. The API echoes the rejected value, for example Not a valid type: invoiceee.

Solution

The amount must be at least INR 1.00.

Error Status: 400

A line-item amount is below the per-currency minimum (100 paise / ₹1.00 for INR). Also returned for zero or negative line-item amounts.

Solution

The amount must be an integer.

Error Status: 400

A non-integer value (for example a decimal like 100.5 or a string like "abc") was passed for a line_items[].amount.

Solution

The quantity must be at least 1.

Error Status: 400

A line-item quantity was passed as 0 or a negative value.

Solution

The email must be a valid email address.

Error Status: 400

The value passed for customer.email is not in a valid email format.

Solution

Contact number contains invalid characters, only digits and + symbol are allowed.

Error Status: 400

The customer.contact value contains characters other than digits and the + symbol.

Solution

The partial payment field must be true or false.

Error Status: 400

A non-boolean value was passed for partial_payment.

Solution

{any extra field} is/are not required and should not be sent.

Error Status: 400

The request body contains fields that are not part of the Invoices API schema.

Solution

Invoices disabled because fee bearer is customer.

Error Status: 400

Your account has the customer fee bearer model enabled, which is not compatible with invoice creation.

Solution

Item cannot be used as it is inactive.

Error Status: 400

A line_items[].item_id passed in the request refers to an item that has been marked inactive.

Solution

The merchant doesn't have international activated.

Error Status: 400

The currency passed is different from your account's default currency, but international payments are not enabled on your account.

Solution

Currency is not supported.

Error Status: 400

The currency value is not a recognised ISO-4217 currency code or is outside the list supported by Razorpay.

Solution

Invoice amount exceeds maximum payment amount allowed.

Error Status: 400

The total invoice amount (sum of line_items[].amount * quantity) exceeds the per-payment maximum configured for your account.

Solution

expire_by should be at least 15 minutes after current time.

Error Status: 400

The expire_by value is in the past or less than 15 minutes from the current server time.

Solution

Request failed. Please try after sometime.

Error Status: 429

You have exceeded the daily rate limit for invoice creation. This per-day rate limit applies to test-mode accounts and unregistered live-mode accounts. In test mode the limit is 300 invoices/day; in live mode for unregistered businesses it is 10,000 invoices/day. Registered live-mode accounts are not subject to this limit.

Solution

Curl

change language

change language

1
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET>
2
-X POST https://api.razorpay.com/v1/invoices \
3
-H 'Content-type: application/json' \
4
-d '{
5
    "type": "invoice",
6
    "date": 1760714528,
7
    "customer_id": "cust_HOQzpsovChhcpl",
8
    "line_items": [
9
        {
10
            "item_id": "item_K6g5L6X43dXjEA"
11
        }
12
    ]
13
}'

Success

Failure

1
{
2
  "id": "inv_K6g5bviu09mXo1",
3
  "entity": "invoice",
4
  "receipt": null,
5
  "invoice_number": null,
6
  "customer_id": "cust_HOQzpsovChhcpl",
7
  "customer_details": {
8
    "id": "cust_HOQzpsovChhcpl",
9
    "name": null,
10
    "email": "alex.lim@example.com",
11
    "contact": "+6591119111",
12
    "gstin": null,
13
    "billing_address": null,
14
    "shipping_address": null,
15
    "customer_name": null,
16
    "customer_email": "alex.lim@example.com",
17
    "customer_contact": "+6591119111"
18
  },
19
  "order_id": "order_K6g5bxSIwYIXJS",
20
  "line_items": [
21
    {
22
      "id": "li_K6g5bwLZuBmb1Q",
23
      "item_id": "item_K6g5L6X43dXjEA",
24
      "ref_id": null,
25
      "ref_type": null,
26
      "name": "Cloth",
27
      "description": "Cotton Cloth",
28
      "amount": 1200,
29
      "unit_amount": 1200,
30
      "gross_amount": 1200,
31
      "tax_amount": 0,
32
      "taxable_amount": 1200,
33
      "net_amount": 1200,
34
      "currency": "",
35
      "type": "invoice",
36
      "tax_inclusive": false,
37
      "hsn_code": null,
38
      "sac_code": null,
39
      "tax_rate": null,
40
      "unit": null,
41
      "quantity": 1,
42
      "taxes": []
43
    }
44
  ],
45
  "payment_id": null,
46
  "status": "issued",
47
  "expire_by": null,
48
  "issued_at": 1660734398,
49
  "paid_at": null,
50
  "cancelled_at": null,
51
  "expired_at": null,
52
  "sms_status": "pending",
53
  "email_status": "pending",
54
  "date": 1760714528,
55
  "terms": null,
56
  "partial_payment": false,
57
  "gross_amount": 1200,
58
  "tax_amount": 0,
59
  "taxable_amount": 1200,
60
  "amount": 1200,
61
  "amount_paid": 0,
62
  "amount_due": 1200,
63
  "currency": "",
64
  "currency_symbol": "<currency_symbol>",
65
  "description": null,
66
  "notes": [],
67
  "comment": null,
68
  "short_url": "https://rzp.io/i/ksYThDL",
69
  "view_less": true,
70
  "billing_start": null,
71
  "billing_end": null,
72
  "type": "invoice",
73
  "group_taxes_discounts": false,
74
  "created_at": 1660734398
75
}