API Test Keys

Create an Invoice With Customer Details

POST

/v1/invoices

Click to copy

Use this endpoint to create an invoice using details such as name, billing_address and shipping_address.

Is this page helpful?

Curl

change language

1curl -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  "description": "Invoice for the month of January 2020",
7  "partial_payment": true,
8  "customer": {
9    "name": " Nur Aisyah",
10    "contact": "+60123456789",
11    "email": "nur.aisyah@example.com",
12    "billing_address": {
13      "line1": "Bakers Street",
14      "line2": "Country Road",
15      "zipcode": "560068",
16      "city": "Bengaluru",
17      "state": "Karnataka",
18      "country": "in"
19    },
20    "shipping_address": {
21      "line1": "Bakers Street",
22      "line2": "Country Road",
23      "zipcode": "560068",
24      "city": "Bengaluru",
25      "state": "Karnataka",
26      "country": "IN"
27    }
28  },
29  "line_items": [
30    {
31      "name": "Master Cloud Computing in 30 Days",
32      "description": "Book by Ravena Ravenclaw",
33      "amount": 399,
34      "currency": "",
35      "quantity": 1
36    }
37  ],
38  "sms_notify": true,
39  "email_notify": false,
40  "currency": "",
41  "expire_by": 1589765167,
42  "notes": {
43    "key1": "Testing."
44  }
45}'

Success

Failure

1{
2  "id": "inv_E7q0tqkxBRzdau",
3  "entity": "invoice",
4  "receipt": null,
5  "invoice_number": null,
6  "customer_id": "cust_E7q0trFqXgExmT",
7  "customer_details": {
8    "id": "cust_E7q0trFqXgExmT",
9    "name": " Nur Aisyah",
10    "email": "nur.aisyah@example.com",
11    "contact": "+60123456789",
12    "gstin": null,
13    "billing_address": {
14      "id": "addr_E7q0ttqh4SGhAC",
15      "type": "billing_address",
16      "primary": true,
17      "line1": "Bakers Street",
18      "line2": "Country Road",
19      "zipcode": "560068",
20      "city": "Bengaluru",
21      "state": "Karnataka",
22      "country": "in"
23    },
24    "shipping_address": {
25      "id": "addr_E7q0ttKwVA1h2V",
26      "type": "shipping_address",
27      "primary": true,
28      "line1": "Bakers Street",
29      "line2": "Country Road",
30      "zipcode": "560068",
31      "city": "Bengaluru",
32      "state": "Karnataka",
33      "country": "in"
34    },
35    "customer_name": " Nur Aisyah",
36    "customer_email": "nur.aisyah@example.com",
37    "customer_contact": "+60123456789"
38  },
39  "order_id": "order_E7q0tvRpC0WJwg",
40  "line_items": [
41    {
42      "id": "li_E7q0tuPNg84VbZ",
43      "item_id": null,
44      "ref_id": null,
45      "ref_type": null,
46      "name": "Master Cloud Computing in 30 Days",
47      "description": "Book by Ravena Ravenclaw",
48      "amount": 399,
49      "unit_amount": 399,
50      "gross_amount": 399,
51      "tax_amount": 0,
52      "taxable_amount": 399,
53      "net_amount": 399,
54      "currency": "",
55      "type": "invoice",
56      "tax_inclusive": false,
57      "hsn_code": null,
58      "sac_code": null,
59      "tax_rate": null,
60      "unit": null,
61      "quantity": 1,
62      "taxes": []
63    }
64  ],
65  "payment_id": null,
66  "status": "issued",
67  "expire_by": 1589765167,
68  "issued_at": 1579765167,
69  "paid_at": null,
70  "cancelled_at": null,
71  "expired_at": null,
72  "sms_status": "pending",
73  "email_status": "pending",
74  "date": 1579765167,
75  "terms": null,
76  "partial_payment": true,
77  "gross_amount": 399,
78  "tax_amount": 0,
79  "taxable_amount": 399,
80  "amount": 399,
81  "amount_paid": 0,
82  "amount_due": 399,
83  "currency": "",
84  "currency_symbol": "$",
85  "description": "Invoice for the month of January 2020",
86  "notes": [],
87  "comment": null,
88  "short_url": "https://rzp.io/i/2wxV8Xs",
89  "view_less": true,
90  "billing_start": null,
91  "billing_end": null,
92  "type": "invoice",
93  "group_taxes_discounts": false,
94  "created_at": 1579765167
95}

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 Curlec 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 Curlec 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: MYR.

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 RM 300.00, 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: MYR.

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

Create an Invoice With Customer Details

POST

/v1/invoices

Click to copy

Use this endpoint to create an invoice using details such as name, billing_address and shipping_address.

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 Curlec 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 Curlec 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: MYR.

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 RM 300.00, 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: MYR.

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

Curl

change language

1curl -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  "description": "Invoice for the month of January 2020",
7  "partial_payment": true,
8  "customer": {
9    "name": " Nur Aisyah",
10    "contact": "+60123456789",
11    "email": "nur.aisyah@example.com",
12    "billing_address": {
13      "line1": "Bakers Street",
14      "line2": "Country Road",
15      "zipcode": "560068",
16      "city": "Bengaluru",
17      "state": "Karnataka",
18      "country": "in"
19    },
20    "shipping_address": {
21      "line1": "Bakers Street",
22      "line2": "Country Road",
23      "zipcode": "560068",
24      "city": "Bengaluru",
25      "state": "Karnataka",
26      "country": "IN"
27    }
28  },
29  "line_items": [
30    {
31      "name": "Master Cloud Computing in 30 Days",
32      "description": "Book by Ravena Ravenclaw",
33      "amount": 399,
34      "currency": "",
35      "quantity": 1
36    }
37  ],
38  "sms_notify": true,
39  "email_notify": false,
40  "currency": "",
41  "expire_by": 1589765167,
42  "notes": {
43    "key1": "Testing."
44  }
45}'

Success

Failure

1{
2  "id": "inv_E7q0tqkxBRzdau",
3  "entity": "invoice",
4  "receipt": null,
5  "invoice_number": null,
6  "customer_id": "cust_E7q0trFqXgExmT",
7  "customer_details": {
8    "id": "cust_E7q0trFqXgExmT",
9    "name": " Nur Aisyah",
10    "email": "nur.aisyah@example.com",
11    "contact": "+60123456789",
12    "gstin": null,
13    "billing_address": {
14      "id": "addr_E7q0ttqh4SGhAC",
15      "type": "billing_address",
16      "primary": true,
17      "line1": "Bakers Street",
18      "line2": "Country Road",
19      "zipcode": "560068",
20      "city": "Bengaluru",
21      "state": "Karnataka",
22      "country": "in"
23    },
24    "shipping_address": {
25      "id": "addr_E7q0ttKwVA1h2V",
26      "type": "shipping_address",
27      "primary": true,
28      "line1": "Bakers Street",
29      "line2": "Country Road",
30      "zipcode": "560068",
31      "city": "Bengaluru",
32      "state": "Karnataka",
33      "country": "in"
34    },
35    "customer_name": " Nur Aisyah",
36    "customer_email": "nur.aisyah@example.com",
37    "customer_contact": "+60123456789"
38  },
39  "order_id": "order_E7q0tvRpC0WJwg",
40  "line_items": [
41    {
42      "id": "li_E7q0tuPNg84VbZ",
43      "item_id": null,
44      "ref_id": null,
45      "ref_type": null,
46      "name": "Master Cloud Computing in 30 Days",
47      "description": "Book by Ravena Ravenclaw",
48      "amount": 399,
49      "unit_amount": 399,
50      "gross_amount": 399,
51      "tax_amount": 0,
52      "taxable_amount": 399,
53      "net_amount": 399,
54      "currency": "",
55      "type": "invoice",
56      "tax_inclusive": false,
57      "hsn_code": null,
58      "sac_code": null,
59      "tax_rate": null,
60      "unit": null,
61      "quantity": 1,
62      "taxes": []
63    }
64  ],
65  "payment_id": null,
66  "status": "issued",
67  "expire_by": 1589765167,
68  "issued_at": 1579765167,
69  "paid_at": null,
70  "cancelled_at": null,
71  "expired_at": null,
72  "sms_status": "pending",
73  "email_status": "pending",
74  "date": 1579765167,
75  "terms": null,
76  "partial_payment": true,
77  "gross_amount": 399,
78  "tax_amount": 0,
79  "taxable_amount": 399,
80  "amount": 399,
81  "amount_paid": 0,
82  "amount_due": 399,
83  "currency": "",
84  "currency_symbol": "$",
85  "description": "Invoice for the month of January 2020",
86  "notes": [],
87  "comment": null,
88  "short_url": "https://rzp.io/i/2wxV8Xs",
89  "view_less": true,
90  "billing_start": null,
91  "billing_end": null,
92  "type": "invoice",
93  "group_taxes_discounts": false,
94  "created_at": 1579765167
95}