Skip to main content
Use this endpoint to create an invoice using details such as name, billing_address and shipping_address.
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

​
Request

Curl

​
Response

Success

​
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 mandatory : 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. 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 : object 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 : object 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 : object 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 300, pass the value as 30000. 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. . 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:
  • true (default): Razorpay sends the notification to the customer.
  • false: You send the notification to the customer.
email_notify optional : 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 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. . notes optional : string Any custom notes added to the invoice. Maximum of 2048 characters.

​
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. 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 : object 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.
  • true: It is the customer’s primary address.
  • false: It is not the customer’s 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 : object 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.
  • true: It is the customer’s primary address.
  • false: It is not the customer’s 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 : object 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. . 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 , 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. 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.

​
Errors

The API “ provided is invalid.
  • code: 4xx
  • description: The API key or secret are not entered or an invalid API key is used.
  • solution: Use and enter the correct API details while executing the API.
customer is required.
  • code: 400
  • description: An invoice is issued without adding customer details.
  • solution: Ensure that the customer details are entered.
the merchant doesn’t have international activated.
  • code: 400
  • description: The line_items object has an international currency set. For example, USD, is not enabled for your account.
  • solution: Ensure that your account has international payments enabled.
Currency of all items should be the same as of the invoice.
  • code: 400
  • description: There is a difference in currency entered between line_items and invoice currency.
  • solution: Ensure that the line_items currency matches that of the invoice.
expire_by should be at least 15 minutes after current time.
  • code: 400
  • description: The expiry date is before or within 15 minutes of the current time
  • solution: Ensure that the Expiry date is greater than the (current time + 15 minutes). For example, if the current time is 1 pm, the expiry date must be at least 1.15 pm.
line_items is required.
  • code: 400
  • description: A mandatory field is empty.
  • solution: Ensure that you fill all the mandatory fields.