{"_id":"57a9ba87d8e951170009c92c","__v":0,"initVersion":{"_id":"54dec8b6c2b4b70d009c3f0f","version":"1"},"user":{"_id":"57a9b83fbfc4af2000270b81","username":"","name":"Prashanth YV"},"project":"54c83b5aab706219009e067b","hidden":true,"createdAt":"2016-08-09T11:12:07.761Z","fullscreen":false,"htmlmode":false,"html":"","body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Private Document\",\n  \"body\": \"This is a private document. Please do not share this link publicly.\"\n}\n[/block]\n# On this Page\n1. [Introduction](#section-introduction)\n2. [Entity structure](#section-entity-structure)\n3. [Understanding Razorpay Invoices](#section-understanding-razorpay-invoices)\n   1. [Using our API](#section--using-our-api-)\n   2. [Invoice Lifecycle](#section--invoice-lifecycle-)\n   3. [Line Items and Items](#section--line-items-and-items-)\n4. [Invoice APIs](#section-invoice-apis)\n   - [Creating an Invoice](#section--creating-an-invoice-)\n   - [Getting an Invoice](#section-getting-an-invoice-)\n   - [Fetching (Get) Multiple Invoices](#section--fetching-get-multiple-invoices-)\n   - [Resending Notification for Invoice](#section--resending-notifications-for-invoice-)\n   - [Get/Downloading PDF of Invoice](#section-get-downloading-pdf-of-an-invoice-)\n   - [Get Status of Invoice](#section-getting-the-status-of-an-invoice-)\n   - [Updating an Invoice](#section--updating-an-invoice-)\n   - [Issuing an Invoice](#section--issuing-an-invoice-)\n   - [Deleting an Invoice](#section--deleting-an-invoice-)\n   - [Cancelling an Invoice](#section--cancelling-an-invoice-)\n5. [Webhooks](#section-webhooks)\n\n# Introduction\n\nThis document covers the details of the Razorpay invoice, its entity structure, and the various operations available with it.\n\nThis API is also used to implement various features such as:\n\n1. [Payment Links](https://docs.razorpay.com/v1/page/link-based-payments)\n2. [eCOD](https://docs.razorpay.com/v1/page/ecod)\n3. [ePOSs](https://razorpay.com/epos/), which is built on top of these APIs.\n\n\n#  Entity Structure \n\nThe following JSON is the representation of the invoice entity. It includes almost all of the public attributes of the entity.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\":\\\"inv_7NZ3uS82Rr6elQ\\\",\\n    \\\"entity\\\":\\\"invoice\\\",\\n    \\\"receipt\\\":\\\"max-14-char-no\\\",\\n    \\\"customer_id\\\":\\\"cust_7NZ3uTXhicUQgQ\\\",\\n    \\\"customer\\\":{\\n        \\\"name\\\":null,\\n        \\\"email\\\":\\\"test@test.com\\\",\\n        \\\"contact\\\":\\\"9999999999\\\",\\n        \\\"billing_address\\\":{\\n            \\\"id\\\":\\\"addr_7NZ3uUd4tI7RCF\\\",\\n            \\\"type\\\":\\\"billing_address\\\",\\n            \\\"primary\\\":true,\\n            \\\"line1\\\":\\\"#11, Navi Camp\\\",\\n            \\\"line2\\\":null,\\n            \\\"zipcode\\\":\\\"560076\\\",\\n            \\\"city\\\":\\\"Pandora\\\",\\n            \\\"state\\\":\\\"Karnataka\\\",\\n            \\\"country\\\":\\\"in\\\"\\n        }\\n    },\\n    \\\"order_id\\\":\\\"order_7NZ3uYBFz5sujN\\\",\\n    \\\"line_items\\\":[\\n        {\\n            \\\"id\\\":\\\"li_7NZ3uW3HUDijJi\\\",\\n            \\\"name\\\":\\\"Book / English August\\\",\\n            \\\"description\\\":null,\\n            \\\"amount\\\":20000,\\n            \\\"currency\\\":\\\"INR\\\",\\n            \\\"quantity\\\":2\\n        },\\n        {\\n            \\\"id\\\":\\\"li_7NZ3uWpp5tWeYB\\\",\\n            \\\"name\\\":\\\"Book / Ignited Minds\\\",\\n            \\\"description\\\":null,\\n            \\\"amount\\\":15000,\\n            \\\"currency\\\":\\\"INR\\\",\\n            \\\"quantity\\\":1\\n        }\\n    ],\\n    \\\"payment_id\\\":null,\\n    \\\"status\\\":\\\"issued\\\",\\n    \\\"expire_by\\\":1498439025,\\n    \\\"issued_at\\\":1488439306,\\n    \\\"paid_at\\\":null,\\n    \\\"expired_at\\\":null,\\n    \\\"sms_status\\\":\\\"pending\\\",\\n    \\\"email_status\\\":\\\"pending\\\",\\n    \\\"date\\\":1488439025,\\n    \\\"terms\\\":\\\"Terms and condition of the service/invoice\\\",\\n    \\\"amount\\\":55000,\\n    \\\"description\\\":\\\"Just an optional description for the invoice\\\",\\n    \\\"notes\\\":{\\n        \\\"random_key\\\":\\\"Random note\\\"\\n    },\\n    \\\"comment\\\":\\\"Optional comment to the customer for the invoice\\\",\\n    \\\"currency\\\":\\\"INR\\\",\\n    \\\"short_url\\\":\\\"http://dwarf.razorpay.dev/013ytd7\\\",\\n    \\\"view_less\\\":true,\\n    \\\"type\\\":\\\"invoice\\\",\\n    \\\"user_id\\\":null,\\n    \\\"created_at\\\":1488439306\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Invoice Entity\"\n    }\n  ]\n}\n[/block]\n# Understanding Razorpay Invoices\n## **Using our API**\nRefer our [Getting started](https://docs.razorpay.com/docs/getting-started) documentation on API integration to understand the basic concepts of our API usage.\n- All the APIs listed below are authenticated via the basic auth.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Auth Requirement\",\n  \"body\": \"All the APIs require basic authentication.\\n\\n**Private APIs:**\\nThe username is the `key_id` and the password is the `key_secret`.\\nThese APIs should always be called from your server and not from the client. `key_secret` should not be exposed to anyone.\\n\\n **Public APIs:** \\nThe username is the `key_id` and the password is empty. These APIs can be called from client side code as well.\"\n}\n[/block]\n\n- Sets of route which belongs to Private and Public group is specified [below](#section-invoice-apis). Authentication as per above guidelines should be used.\n- Following is the API response format in case of errors such as form validation error, bad request errors, etc.:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": {\\n    \\\"code\\\": \\\"BAD_REQUEST_ERROR\\\",\\n    \\\"description\\\": \\\"expire_by should be at least 15 mins after the time of issue.\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error Response Example\"\n    }\n  ]\n}\n[/block]\n## **Invoice Lifecycle**\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c2cf866-Invoice_LifeCycle.jpg\",\n        \"Invoice LifeCycle.jpg\",\n        790,\n        507,\n        \"#cecac5\"\n      ],\n      \"caption\": \"Invoice Lifecycle\"\n    }\n  ]\n}\n[/block]\n- The lifecycle of an invoice can start in either the **Draft** or **Issued** state. (See [Invoice types and creation](#section--4-1-create-invoice-))\n- Only a draft invoice can be deleted. You can cancel an draft/issued invoice. Cancelled invoice are not viewable/payable by customers but it will be listed in your dashboard.\n- Invoice may get into **expired** state after a time (`expire_by`) set during creation.\n- For invoices which have partial payments enabled, **partially paid** would be the status if it's not paid full but only partial amount has been paid till now. Partial payment feature is enabled on per request.\n- **Paid** is the last state of an invoice and no write operations are allowed after an invoice reaches the paid status. It can only be viewed.\n- In the above diagram, all **except deleted** is a state of an invoice, which is available as string value in **status** attribute of invoice entity. Deleted is the actual deletion of invoice and it will not be visible on dashboard view. \n\n## **Line Items and Items**\nAn invoice consists of various line items as shown in the [entity structure](#section-entity-structure). Each line item has details like name, description, amount, quantity, etc. We also have an [Item Entity](https://docs.razorpay.com/v1/page/items) which acts as a template for line item and makes it very easy to reuse same item (as line item) in multiple invoices. \n\nYou can either use the item template as is or override a few attributes without affecting the actual item entity. The section on [Creating an Invoice](#section--creating-an-invoice-) will help you understand the usage better.\n\n# Invoice APIs\nFollowing is a list of APIs for invoices and their operations:\n\n**Private APIs**\n\n- [Creating an Invoice](#section--creating-an-invoice-)\n- [Getting an Invoice](#section-getting-an-invoice-)\n- [Fetching (GET multiple) Invoices](#section--fetching-get-multiple-invoices-)\n- [Updating an Invoice](#section--updating-invoice-)\n- [Issuing an Invoice](##section--issuing-an-invoice-)\n- [Deleting an Invoice](#section--deleting-an-invoice-)\n- [Cancelling an Invoice](#section--cancelling-an-invoice-)\n\n**Public APIs**\n- [Resending Notification for Invoice](#section--resending-notifications-for-invoice-)\n- [Get/downloading PDF of an Invoice](#section-get-downloading-pdf-of-an-invoice-)\n- [Getting the Status of an Invoice](#section-getting-the-status-of-an-invoice-)\n\n## **Creating an Invoice**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"Use this endpoint to create invoices.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Request Body Attributes**\n\nThe following are the explanations of the attributes which can be sent in the request body. <i>(Includes only ones which needs explanation.)</i>\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Data type\",\n    \"h-2\": \"Requirement\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"customer_id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Optional\",\n    \"0-3\": \"If you are using Customers API, you can pass the customer_id in this field. If not, you can pass the **customer** object described below.\",\n    \"1-0\": \"customer[name]\",\n    \"1-1\": \"string\",\n    \"1-2\": \"Mandatory, with customer\",\n    \"2-0\": \"customer[email]\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Mandatory, with customer\",\n    \"3-0\": \"customer[contact]\",\n    \"3-1\": \"string\",\n    \"3-2\": \"Mandatory, with customer\",\n    \"4-0\": \"customer[billing_address][line1]\",\n    \"5-0\": \"customer[billing_address][line2]\",\n    \"6-0\": \"customer[billing_address][city]\",\n    \"7-0\": \"customer[billing_address][zipcode]\",\n    \"8-0\": \"customer[billing_address][state]\",\n    \"9-0\": \"customer[billing_address][country]\",\n    \"4-1\": \"string\",\n    \"5-1\": \"string\",\n    \"6-1\": \"string\",\n    \"7-1\": \"string\",\n    \"8-1\": \"string\",\n    \"9-1\": \"string\",\n    \"4-2\": \"Mandatory, with customer[billing_address]\",\n    \"5-2\": \"Optional\",\n    \"6-2\": \"Mandatory, with customer[billing_address]\",\n    \"7-2\": \"Mandatory, with customer[billing_address]\",\n    \"8-2\": \"Mandatory, with customer[billing_address]\",\n    \"9-2\": \"Mandatory, with customer[billing_address]\",\n    \"13-0\": \"line_items[][name]\",\n    \"13-1\": \"string\",\n    \"13-2\": \"Mandatory, without item_id\",\n    \"12-0\": \"line_items[][item_id]\",\n    \"12-1\": \"string\",\n    \"12-2\": \"Optional\",\n    \"12-3\": \"If you are using Items API, you may use existing item as a template for line items of invoice.\\n\\nYou can still override other details such as name, description by passing these along with item_id. Item will not be updated.\",\n    \"15-0\": \"line_items[][amount]\",\n    \"16-0\": \"line_items[][currency]\",\n    \"17-0\": \"line_items[][quantity]\",\n    \"14-0\": \"line_items[][description]\",\n    \"14-1\": \"string\",\n    \"15-1\": \"integer\",\n    \"16-1\": \"string\",\n    \"17-1\": \"integer\",\n    \"14-2\": \"Optional\",\n    \"15-2\": \"Mandatory, without item_id\",\n    \"16-2\": \"Mandatory, without item_id\",\n    \"17-2\": \"Optional\\ndefault = 1\",\n    \"19-0\": \"expire_by\",\n    \"19-1\": \"epoch/integer\",\n    \"19-2\": \"Optional\\ndefault = 60 days from created time\",\n    \"20-0\": \"sms_notify\",\n    \"20-1\": \"string\\nin: 0|1\",\n    \"20-2\": \"Optional\\ndefault = 1\",\n    \"21-0\": \"email_notify\",\n    \"21-1\": \"string\\nin: 0|1\",\n    \"21-2\": \"Optional\\ndefault = 1\",\n    \"22-0\": \"date\",\n    \"22-1\": \"epoch/integer\",\n    \"22-2\": \"Optional\\ndefault = null\",\n    \"23-0\": \"terms\",\n    \"23-1\": \"string\",\n    \"23-2\": \"Optional\\ndefault = null\",\n    \"11-0\": \"description\",\n    \"11-1\": \"string\",\n    \"11-2\": \"Optional\",\n    \"24-0\": \"notes\",\n    \"24-1\": \"object\",\n    \"24-2\": \"Optional\\ndefault = {}\",\n    \"25-0\": \"comment\",\n    \"25-1\": \"string\",\n    \"25-2\": \"Optional\\ndefault = null\",\n    \"10-0\": \"currency\",\n    \"10-1\": \"string\",\n    \"10-2\": \"Mandatory\",\n    \"26-0\": \"type\",\n    \"26-1\": \"string\\nin: link|ecod|invoice\",\n    \"26-2\": \"Mandatory\",\n    \"10-3\": \"**Only** INR is supported for invoices currently.\",\n    \"16-3\": \"**Only** INR is accepted for now.\\n\\nAlso, this needs to be same as **currency** attribute.\",\n    \"26-3\": \"Must send type=invoice\",\n    \"18-0\": \"partial_payment\",\n    \"18-1\": \"string\\nin: 0|1\",\n    \"18-2\": \"Optional\\ndefault = 0\",\n    \"18-3\": \"Enables partial payments on the invoice.\"\n  },\n  \"cols\": 4,\n  \"rows\": 27\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"customer\\\": {\\n\\t\\t\\\"email\\\": \\\"test@test.com\\\",\\n\\t\\t\\\"contact\\\": \\\"9999999999\\\",\\n\\t\\t\\\"billing_address\\\": {\\n\\t\\t\\t\\\"line1\\\": \\\"#11, Navi Camp\\\",\\n\\t\\t\\t\\\"city\\\": \\\"Pandora\\\",\\n\\t\\t\\t\\\"state\\\": \\\"Karnataka\\\",\\n\\t\\t\\t\\\"zipcode\\\": \\\"560076\\\",\\n\\t\\t\\t\\\"country\\\": \\\"India\\\"\\n\\t\\t}\\n\\t},\\n\\t\\\"line_items\\\": [\\n\\t\\t{\\n\\t\\t\\t\\\"name\\\": \\\"Book / English August\\\",\\n\\t\\t\\t\\\"amount\\\": 20000,\\n\\t\\t\\t\\\"currency\\\": \\\"INR\\\",\\n\\t\\t\\t\\\"quantity\\\": 2\\n\\t\\t},\\n\\t\\t{\\n\\t\\t\\t\\\"name\\\": \\\"Book / Ignited Minds\\\",\\n\\t\\t\\t\\\"amount\\\": 15000,\\n\\t\\t\\t\\\"currency\\\": \\\"INR\\\",\\n\\t\\t\\t\\\"quantity\\\": 1\\n\\t\\t}\\n\\t],\\n\\t\\\"draft\\\": \\\"0\\\",\\n\\t\\\"sms_notify\\\": \\\"1\\\",\\n\\t\\\"email_notify\\\": \\\"1\\\",\\n\\t\\\"date\\\": 1488439025,\\n\\t\\\"receipt\\\": \\\"max-14-char-no\\\",\\n\\t\\\"type\\\": \\\"invoice\\\",\\n\\t\\\"currency\\\": \\\"INR\\\",\\n\\t\\\"expire_by\\\": 1498439025,\\n\\t\\\"terms\\\": \\\"Terms and condition of the service/invoice\\\",\\n\\t\\\"notes\\\": {\\n\\t\\t\\\"random_key\\\": \\\"Random note\\\"\\n\\t},\\n\\t\\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n\\t\\\"comment\\\": \\\"Optional comment to the customer for the invoice\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request #1\"\n    },\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7Nb4lWu28WPV5L\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": \\\"max-14-char-no\\\",\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\",\\n    \\\"billing_address\\\": {\\n      \\\"id\\\": \\\"addr_7NZ3uUd4tI7RCF\\\",\\n      \\\"type\\\": \\\"billing_address\\\",\\n      \\\"primary\\\": true,\\n      \\\"line1\\\": \\\"#11, Navi Camp\\\",\\n      \\\"line2\\\": null,\\n      \\\"zipcode\\\": \\\"560076\\\",\\n      \\\"city\\\": \\\"Pandora\\\",\\n      \\\"state\\\": \\\"Karnataka\\\",\\n      \\\"country\\\": \\\"in\\\"\\n    }\\n  },\\n  \\\"order_id\\\": \\\"order_7Nb4lav01bvoDh\\\",\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_7Nb4lYxT02VP2l\\\",\\n      \\\"name\\\": \\\"Book / English August\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 20000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 2\\n    },\\n    {\\n      \\\"id\\\": \\\"li_7Nb4lZcjZSndqz\\\",\\n      \\\"name\\\": \\\"Book / Ignited Minds\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 15000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 1\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"expire_by\\\": 1498439025,\\n  \\\"issued_at\\\": 1488446398,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"pending\\\",\\n  \\\"email_status\\\": \\\"pending\\\",\\n  \\\"date\\\": 1488439025,\\n  \\\"terms\\\": \\\"Terms and condition of the service/invoice\\\",\\n  \\\"amount\\\": 55000,\\n  \\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n  \\\"notes\\\": {\\n    \\\"random_key\\\": \\\"Random note\\\"\\n  },\\n  \\\"comment\\\": \\\"Optional comment to the customer for the invoice\\\",\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/fdtgkve\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"invoice\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488446398\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #1\"\n    }\n  ]\n}\n[/block]\nNote:\n- You can create a blank (with no details at all) invoice in `draft` status and then update it with necessary information and then issue it later with [this API](#section--4-8-issue-invoice-).\n- Only after the invoice is issued, you will get a short URL. Also, only after the invoice is issued, it can be sent to customers and the corresponding payment can be made against it.\n- You can use [Items APIs](https://docs.razorpay.com/v1/page/items) to create items which you can later use as a template to create line items in an invoice.\n\n## Getting an Invoice**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Methdo\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices/{id}\",\n    \"0-2\": \"Gets invoice with the given ID.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7NbHv4vLbrvzPs\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": \\\"max-14-char-n2\\\",\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\",\\n    \\\"billing_address\\\": {\\n      \\\"id\\\": \\\"addr_7NZ3uUd4tI7RCF\\\",\\n      \\\"type\\\": \\\"billing_address\\\",\\n      \\\"primary\\\": true,\\n      \\\"line1\\\": \\\"#11, Navi Camp\\\",\\n      \\\"line2\\\": null,\\n      \\\"zipcode\\\": \\\"560076\\\",\\n      \\\"city\\\": \\\"Pandora\\\",\\n      \\\"state\\\": \\\"Karnataka\\\",\\n      \\\"country\\\": \\\"in\\\"\\n    }\\n  },\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": null,\\n    \\\"customer_email\\\": \\\"test@test.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_7NbHv8f5jgYemg\\\",\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_7NbHv7B3bD6sbK\\\",\\n      \\\"name\\\": \\\"Book / English August\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 20000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 2\\n    },\\n    {\\n      \\\"id\\\": \\\"li_7NbHv7l7YS4Wyb\\\",\\n      \\\"name\\\": \\\"Book / Ignited Minds\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 15000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 1\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"expire_by\\\": 1498439025,\\n  \\\"issued_at\\\": 1488447145,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"sent\\\",\\n  \\\"email_status\\\": \\\"sent\\\",\\n  \\\"date\\\": 1488439025,\\n  \\\"terms\\\": \\\"Terms and condition of the service/invoice\\\",\\n  \\\"amount\\\": 55000,\\n  \\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n  \\\"notes\\\": {\\n    \\\"random_key\\\": \\\"Random note\\\"\\n  },\\n  \\\"comment\\\": \\\"Optional comment to the customer for the invoice\\\",\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/flui3ex\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"invoice\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488447145\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## **Fetching (get) multiple Invoices **\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"h-3\": \"Accepted query params\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices\",\n    \"0-2\": \"Fetches multiple invoices\",\n    \"0-3\": \"- payment_id\\n- receipt\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"entity\\\": \\\"collection\\\",\\n  \\\"count\\\": 2,\\n  \\\"items\\\": [\\n    {\\n      \\\"id\\\": \\\"inv_7NbHv4vLbrvzPs\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": \\\"max-14-char-n2\\\",\\n      \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n      \\\"customer\\\": {\\n        \\\"name\\\": null,\\n        \\\"email\\\": \\\"test@test.com\\\",\\n        \\\"contact\\\": \\\"9999999999\\\",\\n        \\\"billing_address\\\": {\\n          \\\"id\\\": \\\"addr_7NZ3uUd4tI7RCF\\\",\\n          \\\"type\\\": \\\"billing_address\\\",\\n          \\\"primary\\\": true,\\n          \\\"line1\\\": \\\"#11, Navi Camp\\\",\\n          \\\"line2\\\": null,\\n          \\\"zipcode\\\": \\\"560076\\\",\\n          \\\"city\\\": \\\"Pandora\\\",\\n          \\\"state\\\": \\\"Karnataka\\\",\\n          \\\"country\\\": \\\"in\\\"\\n        }\\n      },\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": null,\\n        \\\"customer_email\\\": \\\"test@test.com\\\",\\n        \\\"customer_contact\\\": \\\"9999999999\\\",\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": \\\"order_7NbHv8f5jgYemg\\\",\\n      \\\"line_items\\\": [\\n        {\\n          \\\"id\\\": \\\"li_7NbHv7B3bD6sbK\\\",\\n          \\\"name\\\": \\\"Book / English August\\\",\\n          \\\"description\\\": null,\\n          \\\"amount\\\": 20000,\\n          \\\"currency\\\": \\\"INR\\\",\\n          \\\"quantity\\\": 2\\n        },\\n        {\\n          \\\"id\\\": \\\"li_7NbHv7l7YS4Wyb\\\",\\n          \\\"name\\\": \\\"Book / Ignited Minds\\\",\\n          \\\"description\\\": null,\\n          \\\"amount\\\": 15000,\\n          \\\"currency\\\": \\\"INR\\\",\\n          \\\"quantity\\\": 1\\n        }\\n      ],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"issued\\\",\\n      \\\"expire_by\\\": 1498439025,\\n      \\\"issued_at\\\": 1488447145,\\n      \\\"paid_at\\\": null,\\n      \\\"expired_at\\\": null,\\n      \\\"sms_status\\\": \\\"sent\\\",\\n      \\\"email_status\\\": \\\"sent\\\",\\n      \\\"date\\\": 1488439025,\\n      \\\"terms\\\": \\\"Terms and condition of the service/invoice\\\",\\n      \\\"amount\\\": 55000,\\n      \\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n      \\\"notes\\\": {\\n        \\\"random_key\\\": \\\"Random note\\\"\\n      },\\n      \\\"comment\\\": \\\"Optional comment to the customer for the invoice\\\",\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/flui3ex\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": \\\"invoice\\\",\\n      \\\"user_id\\\": null,\\n      \\\"created_at\\\": 1488447145\\n    },\\n    {\\n      \\\"id\\\": \\\"inv_7Nb8kOvRzHP1jc\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": null,\\n      \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n      \\\"customer\\\": {\\n        \\\"name\\\": null,\\n        \\\"email\\\": \\\"test@test.com\\\",\\n        \\\"contact\\\": \\\"9999999999\\\"\\n      },\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": null,\\n        \\\"customer_email\\\": \\\"test@test.com\\\",\\n        \\\"customer_contact\\\": \\\"9999999999\\\",\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": null,\\n      \\\"line_items\\\": [],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"draft\\\",\\n      \\\"expire_by\\\": 1493630624,\\n      \\\"issued_at\\\": null,\\n      \\\"paid_at\\\": null,\\n      \\\"expired_at\\\": null,\\n      \\\"sms_status\\\": \\\"pending\\\",\\n      \\\"email_status\\\": \\\"pending\\\",\\n      \\\"date\\\": 1488446624,\\n      \\\"terms\\\": null,\\n      \\\"amount\\\": null,\\n      \\\"description\\\": null,\\n      \\\"notes\\\": [],\\n      \\\"comment\\\": null,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/x0jkqbu\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": \\\"invoice\\\",\\n      \\\"user_id\\\": null,\\n      \\\"created_at\\\": 1488446624\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## **Resending Notifications for Invoice **\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices/{id}/notify/{medium}\",\n    \"0-2\": \"Notifies customer via email or SMS.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"success\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## Get/downloading PDF of an Invoice **\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"Get or download the most recent PDF version of an invoice.\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices/{id}/pdf\",\n    \"h-3\": \"Accepted query params\",\n    \"0-3\": \"- download, in:0|1\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n## Getting the Status of an Invoice **\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices/{id}/status\",\n    \"0-2\": \"Returns invoice status if it has not been paid or the payment_id if it has been paid.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"status\\\": \\\"issued\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #1\"\n    },\n    {\n      \"code\": \"{\\n\\t\\\"razorpay_payment_id\\\": \\\"pay_jflajlga89hlJj\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #2\"\n    }\n  ]\n}\n[/block]\n## **Updating an Invoice** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"h-3\": \"Accepted attributes in request body\",\n    \"0-0\": \"PATCH\",\n    \"0-1\": \"/invoices/{id}\",\n    \"0-2\": \"Updates an existing invoice\",\n    \"0-3\": \"All validation rules apply as described above in [Request Body Attributes](#section--4-1-create-invoice-) section.\\n- For invoice in **Draft** state:\\n  -sms_notify\\n  -email_notify\\n  -date\\n  -terms\\n  -notes\\n  -comment\\n  -receipt\\n  -view_less\\n  -source\\n  -type\\n  -customer\\n  -customer_id\\n  -line_items\\n  -amount\\n  -description\\n  -user_id\\n  -expire_by\\n  -draft\\n- For invoice in **Issued** state:\\n  -terms\\n  -notes\\n  -comment\\n  -receipt\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"line_items\\\": [\\n\\t    {\\n\\t      \\\"id\\\": \\\"li_7Nf9KyLyQVZDUS\\\",\\n\\t      \\\"name\\\": \\\"Book / English August - Updated name and quantity\\\",\\n\\t      \\\"quantity\\\": 5\\n\\t    },\\n\\t    {\\n\\t      \\\"name\\\": \\\"Book / Elon Musk's Autobiography\\\",\\n\\t      \\\"amount\\\": 25000,\\n\\t      \\\"currency\\\": \\\"INR\\\",\\n\\t      \\\"quantity\\\": 2\\n\\t    }\\n\\t],\\n\\t\\\"notes\\\": {\\n\\t\\t\\\"updated-key\\\": \\\"Updated Notes value\\\"\\n\\t}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request #1\"\n    },\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7Nf9KwQdBsM2WH\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": \\\"max-14-char-n4\\\",\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\",\\n    \\\"billing_address\\\": {\\n      \\\"id\\\": \\\"addr_7NZ3uUd4tI7RCF\\\",\\n      \\\"type\\\": \\\"billing_address\\\",\\n      \\\"primary\\\": true,\\n      \\\"line1\\\": \\\"#11, Navi Camp\\\",\\n      \\\"line2\\\": null,\\n      \\\"zipcode\\\": \\\"560076\\\",\\n      \\\"city\\\": \\\"Pandora\\\",\\n      \\\"state\\\": \\\"Karnataka\\\",\\n      \\\"country\\\": \\\"in\\\"\\n    }\\n  },\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": null,\\n    \\\"customer_email\\\": \\\"test@test.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": null,\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_7Nf9KyLyQVZDUS\\\",\\n      \\\"name\\\": \\\"Book / English August - Updated name and quantity\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 20000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 5\\n    },\\n    {\\n      \\\"id\\\": \\\"li_7NfBtHIo7uTAeh\\\",\\n      \\\"name\\\": \\\"Book / Elon Musk's Autobiography\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 25000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 2\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"draft\\\",\\n  \\\"expire_by\\\": 1498439025,\\n  \\\"issued_at\\\": null,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"pending\\\",\\n  \\\"email_status\\\": \\\"pending\\\",\\n  \\\"date\\\": 1488439025,\\n  \\\"terms\\\": \\\"Terms and condition of the service/invoice\\\",\\n  \\\"amount\\\": 150000,\\n  \\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n  \\\"notes\\\": {\\n    \\\"updated-key\\\": \\\"Updated Notes value\\\"\\n  },\\n  \\\"comment\\\": \\\"Optional comment to the customer for the invoice\\\",\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": null,\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"invoice\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488460744\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #1\"\n    },\n    {\n      \"code\": \"{\\n\\t\\\"terms\\\": \\\"Updated terms and conditions\\\",\\n\\t\\\"comment\\\": \\\"Updated comment for customer\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request #2\"\n    },\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7NbHv4vLbrvzPs\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": \\\"max-14-char-n2\\\",\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\",\\n    \\\"billing_address\\\": {\\n      \\\"id\\\": \\\"addr_7NZ3uUd4tI7RCF\\\",\\n      \\\"type\\\": \\\"billing_address\\\",\\n      \\\"primary\\\": true,\\n      \\\"line1\\\": \\\"#11, Navi Camp\\\",\\n      \\\"line2\\\": null,\\n      \\\"zipcode\\\": \\\"560076\\\",\\n      \\\"city\\\": \\\"Pandora\\\",\\n      \\\"state\\\": \\\"Karnataka\\\",\\n      \\\"country\\\": \\\"in\\\"\\n    }\\n  },\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": null,\\n    \\\"customer_email\\\": \\\"test@test.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_7NbHv8f5jgYemg\\\",\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_7NbHv7B3bD6sbK\\\",\\n      \\\"name\\\": \\\"Book / English August\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 20000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 2\\n    },\\n    {\\n      \\\"id\\\": \\\"li_7NbHv7l7YS4Wyb\\\",\\n      \\\"name\\\": \\\"Book / Ignited Minds\\\",\\n      \\\"description\\\": null,\\n      \\\"amount\\\": 15000,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"quantity\\\": 1\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"expire_by\\\": 1498439025,\\n  \\\"issued_at\\\": 1488447145,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"sent\\\",\\n  \\\"email_status\\\": \\\"sent\\\",\\n  \\\"date\\\": 1488439025,\\n  \\\"terms\\\": \\\"Updated terms and conditions\\\",\\n  \\\"amount\\\": 55000,\\n  \\\"description\\\": \\\"Just an optional description for the invoice\\\",\\n  \\\"notes\\\": {\\n    \\\"random_key\\\": \\\"Random note\\\"\\n  },\\n  \\\"comment\\\": \\\"Updated comment for customer\\\",\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/flui3ex\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"invoice\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488447145\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #2\"\n    }\n  ]\n}\n[/block]\nNotes:\n- Invoice update is a patch request and `line_items` is treated as an attribute. So when you send line_items array, you would be adding a new line_items to an invoice. For example, in Request #1 - line_items with id `li_7Nf9KyLyQVZDUS` 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.\n- You can only send fields (as pointed above) which are allowed to be edited in given invoice state. Otherwise it will throw a bad request error.\n\n## **Issuing an Invoice** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices/{id}/issue\",\n    \"0-2\": \"Issues an invoice in draft status. Short URL only gets created when the invoice is in issued state. Only then can the customer make the payment.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n- It can only be called on an invoice that is in the draft state.\n- It's response is the invoice entity, similar to create/update API response.\n\n## **Deleting an Invoice** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"DELETE\",\n    \"0-1\": \"/invoices/{id}\",\n    \"0-2\": \"Deletes an invoice which is in the draft status.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\nThe response is always be an empty array, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[]\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## **Cancelling an Invoice** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices/{id}/cancel\",\n    \"0-2\": \"Cancels an unpaid invoice.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n- It can only be called on an invoice that is not in the paid state.\n- It's response is the invoice entity, similar to create/update API response with `status` attribute's value as `cancelled`.\n\n# Webhooks\n\nWe have a webhook `invoice.paid` which gets fired whenever an invoice is successfully paid by a customer.\nEvery invoice is essentially linked to an order. So when a payment corresponding to an invoice is completed, you will receive both the `invoice.paid` webhook, as well as the `order.paid` webhook.\n\nIf you are not using Orders API, you can disable `order.paid` webhook via the Dashboard.\n\nYou can find more details about webhooks and `invoice.paid` event here:\n[https://docs.razorpay.com/v1/page/webhooks](https://docs.razorpay.com/v1/page/webhooks) \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"An early access program to complete invoicing feature is now available via the Dashboard. Drop us an email at support@razorpay.com to be a part of the program.\"\n}\n[/block]","slug":"invoices","title":"Invoices"}

Invoices


[block:callout] { "type": "danger", "title": "Private Document", "body": "This is a private document. Please do not share this link publicly." } [/block] # On this Page 1. [Introduction](#section-introduction) 2. [Entity structure](#section-entity-structure) 3. [Understanding Razorpay Invoices](#section-understanding-razorpay-invoices) 1. [Using our API](#section--using-our-api-) 2. [Invoice Lifecycle](#section--invoice-lifecycle-) 3. [Line Items and Items](#section--line-items-and-items-) 4. [Invoice APIs](#section-invoice-apis) - [Creating an Invoice](#section--creating-an-invoice-) - [Getting an Invoice](#section-getting-an-invoice-) - [Fetching (Get) Multiple Invoices](#section--fetching-get-multiple-invoices-) - [Resending Notification for Invoice](#section--resending-notifications-for-invoice-) - [Get/Downloading PDF of Invoice](#section-get-downloading-pdf-of-an-invoice-) - [Get Status of Invoice](#section-getting-the-status-of-an-invoice-) - [Updating an Invoice](#section--updating-an-invoice-) - [Issuing an Invoice](#section--issuing-an-invoice-) - [Deleting an Invoice](#section--deleting-an-invoice-) - [Cancelling an Invoice](#section--cancelling-an-invoice-) 5. [Webhooks](#section-webhooks) # Introduction This document covers the details of the Razorpay invoice, its entity structure, and the various operations available with it. This API is also used to implement various features such as: 1. [Payment Links](https://docs.razorpay.com/v1/page/link-based-payments) 2. [eCOD](https://docs.razorpay.com/v1/page/ecod) 3. [ePOSs](https://razorpay.com/epos/), which is built on top of these APIs. # Entity Structure The following JSON is the representation of the invoice entity. It includes almost all of the public attributes of the entity. [block:code] { "codes": [ { "code": "{\n \"id\":\"inv_7NZ3uS82Rr6elQ\",\n \"entity\":\"invoice\",\n \"receipt\":\"max-14-char-no\",\n \"customer_id\":\"cust_7NZ3uTXhicUQgQ\",\n \"customer\":{\n \"name\":null,\n \"email\":\"test@test.com\",\n \"contact\":\"9999999999\",\n \"billing_address\":{\n \"id\":\"addr_7NZ3uUd4tI7RCF\",\n \"type\":\"billing_address\",\n \"primary\":true,\n \"line1\":\"#11, Navi Camp\",\n \"line2\":null,\n \"zipcode\":\"560076\",\n \"city\":\"Pandora\",\n \"state\":\"Karnataka\",\n \"country\":\"in\"\n }\n },\n \"order_id\":\"order_7NZ3uYBFz5sujN\",\n \"line_items\":[\n {\n \"id\":\"li_7NZ3uW3HUDijJi\",\n \"name\":\"Book / English August\",\n \"description\":null,\n \"amount\":20000,\n \"currency\":\"INR\",\n \"quantity\":2\n },\n {\n \"id\":\"li_7NZ3uWpp5tWeYB\",\n \"name\":\"Book / Ignited Minds\",\n \"description\":null,\n \"amount\":15000,\n \"currency\":\"INR\",\n \"quantity\":1\n }\n ],\n \"payment_id\":null,\n \"status\":\"issued\",\n \"expire_by\":1498439025,\n \"issued_at\":1488439306,\n \"paid_at\":null,\n \"expired_at\":null,\n \"sms_status\":\"pending\",\n \"email_status\":\"pending\",\n \"date\":1488439025,\n \"terms\":\"Terms and condition of the service/invoice\",\n \"amount\":55000,\n \"description\":\"Just an optional description for the invoice\",\n \"notes\":{\n \"random_key\":\"Random note\"\n },\n \"comment\":\"Optional comment to the customer for the invoice\",\n \"currency\":\"INR\",\n \"short_url\":\"http://dwarf.razorpay.dev/013ytd7\",\n \"view_less\":true,\n \"type\":\"invoice\",\n \"user_id\":null,\n \"created_at\":1488439306\n}", "language": "json", "name": "Invoice Entity" } ] } [/block] # Understanding Razorpay Invoices ## **Using our API** Refer our [Getting started](https://docs.razorpay.com/docs/getting-started) documentation on API integration to understand the basic concepts of our API usage. - All the APIs listed below are authenticated via the basic auth. [block:callout] { "type": "info", "title": "Auth Requirement", "body": "All the APIs require basic authentication.\n\n**Private APIs:**\nThe username is the `key_id` and the password is the `key_secret`.\nThese APIs should always be called from your server and not from the client. `key_secret` should not be exposed to anyone.\n\n **Public APIs:** \nThe username is the `key_id` and the password is empty. These APIs can be called from client side code as well." } [/block] - Sets of route which belongs to Private and Public group is specified [below](#section-invoice-apis). Authentication as per above guidelines should be used. - Following is the API response format in case of errors such as form validation error, bad request errors, etc.: [block:code] { "codes": [ { "code": "{\n \"error\": {\n \"code\": \"BAD_REQUEST_ERROR\",\n \"description\": \"expire_by should be at least 15 mins after the time of issue.\"\n }\n}", "language": "json", "name": "Error Response Example" } ] } [/block] ## **Invoice Lifecycle** [block:image] { "images": [ { "image": [ "https://files.readme.io/c2cf866-Invoice_LifeCycle.jpg", "Invoice LifeCycle.jpg", 790, 507, "#cecac5" ], "caption": "Invoice Lifecycle" } ] } [/block] - The lifecycle of an invoice can start in either the **Draft** or **Issued** state. (See [Invoice types and creation](#section--4-1-create-invoice-)) - Only a draft invoice can be deleted. You can cancel an draft/issued invoice. Cancelled invoice are not viewable/payable by customers but it will be listed in your dashboard. - Invoice may get into **expired** state after a time (`expire_by`) set during creation. - For invoices which have partial payments enabled, **partially paid** would be the status if it's not paid full but only partial amount has been paid till now. Partial payment feature is enabled on per request. - **Paid** is the last state of an invoice and no write operations are allowed after an invoice reaches the paid status. It can only be viewed. - In the above diagram, all **except deleted** is a state of an invoice, which is available as string value in **status** attribute of invoice entity. Deleted is the actual deletion of invoice and it will not be visible on dashboard view. ## **Line Items and Items** An invoice consists of various line items as shown in the [entity structure](#section-entity-structure). Each line item has details like name, description, amount, quantity, etc. We also have an [Item Entity](https://docs.razorpay.com/v1/page/items) which acts as a template for line item and makes it very easy to reuse same item (as line item) in multiple invoices. You can either use the item template as is or override a few attributes without affecting the actual item entity. The section on [Creating an Invoice](#section--creating-an-invoice-) will help you understand the usage better. # Invoice APIs Following is a list of APIs for invoices and their operations: **Private APIs** - [Creating an Invoice](#section--creating-an-invoice-) - [Getting an Invoice](#section-getting-an-invoice-) - [Fetching (GET multiple) Invoices](#section--fetching-get-multiple-invoices-) - [Updating an Invoice](#section--updating-invoice-) - [Issuing an Invoice](##section--issuing-an-invoice-) - [Deleting an Invoice](#section--deleting-an-invoice-) - [Cancelling an Invoice](#section--cancelling-an-invoice-) **Public APIs** - [Resending Notification for Invoice](#section--resending-notifications-for-invoice-) - [Get/downloading PDF of an Invoice](#section-get-downloading-pdf-of-an-invoice-) - [Getting the Status of an Invoice](#section-getting-the-status-of-an-invoice-) ## **Creating an Invoice** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "0-0": "POST", "0-1": "/invoices", "h-2": "Description", "0-2": "Use this endpoint to create invoices." }, "cols": 3, "rows": 1 } [/block] **Request Body Attributes** The following are the explanations of the attributes which can be sent in the request body. <i>(Includes only ones which needs explanation.)</i> [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Data type", "h-2": "Requirement", "h-3": "Description", "0-0": "customer_id", "0-1": "string", "0-2": "Optional", "0-3": "If you are using Customers API, you can pass the customer_id in this field. If not, you can pass the **customer** object described below.", "1-0": "customer[name]", "1-1": "string", "1-2": "Mandatory, with customer", "2-0": "customer[email]", "2-1": "string", "2-2": "Mandatory, with customer", "3-0": "customer[contact]", "3-1": "string", "3-2": "Mandatory, with customer", "4-0": "customer[billing_address][line1]", "5-0": "customer[billing_address][line2]", "6-0": "customer[billing_address][city]", "7-0": "customer[billing_address][zipcode]", "8-0": "customer[billing_address][state]", "9-0": "customer[billing_address][country]", "4-1": "string", "5-1": "string", "6-1": "string", "7-1": "string", "8-1": "string", "9-1": "string", "4-2": "Mandatory, with customer[billing_address]", "5-2": "Optional", "6-2": "Mandatory, with customer[billing_address]", "7-2": "Mandatory, with customer[billing_address]", "8-2": "Mandatory, with customer[billing_address]", "9-2": "Mandatory, with customer[billing_address]", "13-0": "line_items[][name]", "13-1": "string", "13-2": "Mandatory, without item_id", "12-0": "line_items[][item_id]", "12-1": "string", "12-2": "Optional", "12-3": "If you are using Items API, you may use existing item as a template for line items of invoice.\n\nYou can still override other details such as name, description by passing these along with item_id. Item will not be updated.", "15-0": "line_items[][amount]", "16-0": "line_items[][currency]", "17-0": "line_items[][quantity]", "14-0": "line_items[][description]", "14-1": "string", "15-1": "integer", "16-1": "string", "17-1": "integer", "14-2": "Optional", "15-2": "Mandatory, without item_id", "16-2": "Mandatory, without item_id", "17-2": "Optional\ndefault = 1", "19-0": "expire_by", "19-1": "epoch/integer", "19-2": "Optional\ndefault = 60 days from created time", "20-0": "sms_notify", "20-1": "string\nin: 0|1", "20-2": "Optional\ndefault = 1", "21-0": "email_notify", "21-1": "string\nin: 0|1", "21-2": "Optional\ndefault = 1", "22-0": "date", "22-1": "epoch/integer", "22-2": "Optional\ndefault = null", "23-0": "terms", "23-1": "string", "23-2": "Optional\ndefault = null", "11-0": "description", "11-1": "string", "11-2": "Optional", "24-0": "notes", "24-1": "object", "24-2": "Optional\ndefault = {}", "25-0": "comment", "25-1": "string", "25-2": "Optional\ndefault = null", "10-0": "currency", "10-1": "string", "10-2": "Mandatory", "26-0": "type", "26-1": "string\nin: link|ecod|invoice", "26-2": "Mandatory", "10-3": "**Only** INR is supported for invoices currently.", "16-3": "**Only** INR is accepted for now.\n\nAlso, this needs to be same as **currency** attribute.", "26-3": "Must send type=invoice", "18-0": "partial_payment", "18-1": "string\nin: 0|1", "18-2": "Optional\ndefault = 0", "18-3": "Enables partial payments on the invoice." }, "cols": 4, "rows": 27 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n\t\"customer\": {\n\t\t\"email\": \"test@test.com\",\n\t\t\"contact\": \"9999999999\",\n\t\t\"billing_address\": {\n\t\t\t\"line1\": \"#11, Navi Camp\",\n\t\t\t\"city\": \"Pandora\",\n\t\t\t\"state\": \"Karnataka\",\n\t\t\t\"zipcode\": \"560076\",\n\t\t\t\"country\": \"India\"\n\t\t}\n\t},\n\t\"line_items\": [\n\t\t{\n\t\t\t\"name\": \"Book / English August\",\n\t\t\t\"amount\": 20000,\n\t\t\t\"currency\": \"INR\",\n\t\t\t\"quantity\": 2\n\t\t},\n\t\t{\n\t\t\t\"name\": \"Book / Ignited Minds\",\n\t\t\t\"amount\": 15000,\n\t\t\t\"currency\": \"INR\",\n\t\t\t\"quantity\": 1\n\t\t}\n\t],\n\t\"draft\": \"0\",\n\t\"sms_notify\": \"1\",\n\t\"email_notify\": \"1\",\n\t\"date\": 1488439025,\n\t\"receipt\": \"max-14-char-no\",\n\t\"type\": \"invoice\",\n\t\"currency\": \"INR\",\n\t\"expire_by\": 1498439025,\n\t\"terms\": \"Terms and condition of the service/invoice\",\n\t\"notes\": {\n\t\t\"random_key\": \"Random note\"\n\t},\n\t\"description\": \"Just an optional description for the invoice\",\n\t\"comment\": \"Optional comment to the customer for the invoice\"\n}", "language": "json", "name": "Request #1" }, { "code": "{\n \"id\": \"inv_7Nb4lWu28WPV5L\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-no\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n \"billing_address\": {\n \"id\": \"addr_7NZ3uUd4tI7RCF\",\n \"type\": \"billing_address\",\n \"primary\": true,\n \"line1\": \"#11, Navi Camp\",\n \"line2\": null,\n \"zipcode\": \"560076\",\n \"city\": \"Pandora\",\n \"state\": \"Karnataka\",\n \"country\": \"in\"\n }\n },\n \"order_id\": \"order_7Nb4lav01bvoDh\",\n \"line_items\": [\n {\n \"id\": \"li_7Nb4lYxT02VP2l\",\n \"name\": \"Book / English August\",\n \"description\": null,\n \"amount\": 20000,\n \"currency\": \"INR\",\n \"quantity\": 2\n },\n {\n \"id\": \"li_7Nb4lZcjZSndqz\",\n \"name\": \"Book / Ignited Minds\",\n \"description\": null,\n \"amount\": 15000,\n \"currency\": \"INR\",\n \"quantity\": 1\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1498439025,\n \"issued_at\": 1488446398,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"pending\",\n \"email_status\": \"pending\",\n \"date\": 1488439025,\n \"terms\": \"Terms and condition of the service/invoice\",\n \"amount\": 55000,\n \"description\": \"Just an optional description for the invoice\",\n \"notes\": {\n \"random_key\": \"Random note\"\n },\n \"comment\": \"Optional comment to the customer for the invoice\",\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/fdtgkve\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488446398\n}", "language": "json", "name": "Response #1" } ] } [/block] Note: - You can create a blank (with no details at all) invoice in `draft` status and then update it with necessary information and then issue it later with [this API](#section--4-8-issue-invoice-). - Only after the invoice is issued, you will get a short URL. Also, only after the invoice is issued, it can be sent to customers and the corresponding payment can be made against it. - You can use [Items APIs](https://docs.razorpay.com/v1/page/items) to create items which you can later use as a template to create line items in an invoice. ## Getting an Invoice** [block:parameters] { "data": { "h-0": "Methdo", "h-1": "Endpoint", "h-2": "Description", "0-0": "GET", "0-1": "/invoices/{id}", "0-2": "Gets invoice with the given ID." }, "cols": 3, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n \"id\": \"inv_7NbHv4vLbrvzPs\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-n2\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n \"billing_address\": {\n \"id\": \"addr_7NZ3uUd4tI7RCF\",\n \"type\": \"billing_address\",\n \"primary\": true,\n \"line1\": \"#11, Navi Camp\",\n \"line2\": null,\n \"zipcode\": \"560076\",\n \"city\": \"Pandora\",\n \"state\": \"Karnataka\",\n \"country\": \"in\"\n }\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7NbHv8f5jgYemg\",\n \"line_items\": [\n {\n \"id\": \"li_7NbHv7B3bD6sbK\",\n \"name\": \"Book / English August\",\n \"description\": null,\n \"amount\": 20000,\n \"currency\": \"INR\",\n \"quantity\": 2\n },\n {\n \"id\": \"li_7NbHv7l7YS4Wyb\",\n \"name\": \"Book / Ignited Minds\",\n \"description\": null,\n \"amount\": 15000,\n \"currency\": \"INR\",\n \"quantity\": 1\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1498439025,\n \"issued_at\": 1488447145,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"sent\",\n \"email_status\": \"sent\",\n \"date\": 1488439025,\n \"terms\": \"Terms and condition of the service/invoice\",\n \"amount\": 55000,\n \"description\": \"Just an optional description for the invoice\",\n \"notes\": {\n \"random_key\": \"Random note\"\n },\n \"comment\": \"Optional comment to the customer for the invoice\",\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/flui3ex\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488447145\n}", "language": "json", "name": "Response" } ] } [/block] ## **Fetching (get) multiple Invoices ** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "h-3": "Accepted query params", "0-0": "GET", "0-1": "/invoices", "0-2": "Fetches multiple invoices", "0-3": "- payment_id\n- receipt" }, "cols": 4, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n \"entity\": \"collection\",\n \"count\": 2,\n \"items\": [\n {\n \"id\": \"inv_7NbHv4vLbrvzPs\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-n2\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n \"billing_address\": {\n \"id\": \"addr_7NZ3uUd4tI7RCF\",\n \"type\": \"billing_address\",\n \"primary\": true,\n \"line1\": \"#11, Navi Camp\",\n \"line2\": null,\n \"zipcode\": \"560076\",\n \"city\": \"Pandora\",\n \"state\": \"Karnataka\",\n \"country\": \"in\"\n }\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7NbHv8f5jgYemg\",\n \"line_items\": [\n {\n \"id\": \"li_7NbHv7B3bD6sbK\",\n \"name\": \"Book / English August\",\n \"description\": null,\n \"amount\": 20000,\n \"currency\": \"INR\",\n \"quantity\": 2\n },\n {\n \"id\": \"li_7NbHv7l7YS4Wyb\",\n \"name\": \"Book / Ignited Minds\",\n \"description\": null,\n \"amount\": 15000,\n \"currency\": \"INR\",\n \"quantity\": 1\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1498439025,\n \"issued_at\": 1488447145,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"sent\",\n \"email_status\": \"sent\",\n \"date\": 1488439025,\n \"terms\": \"Terms and condition of the service/invoice\",\n \"amount\": 55000,\n \"description\": \"Just an optional description for the invoice\",\n \"notes\": {\n \"random_key\": \"Random note\"\n },\n \"comment\": \"Optional comment to the customer for the invoice\",\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/flui3ex\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488447145\n },\n {\n \"id\": \"inv_7Nb8kOvRzHP1jc\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\"\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": null,\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"draft\",\n \"expire_by\": 1493630624,\n \"issued_at\": null,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"pending\",\n \"email_status\": \"pending\",\n \"date\": 1488446624,\n \"terms\": null,\n \"amount\": null,\n \"description\": null,\n \"notes\": [],\n \"comment\": null,\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/x0jkqbu\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488446624\n }\n ]\n}", "language": "json", "name": "Response" } ] } [/block] ## **Resending Notifications for Invoice ** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "POST", "0-1": "/invoices/{id}/notify/{medium}", "0-2": "Notifies customer via email or SMS." }, "cols": 3, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "json", "name": "Response" } ] } [/block] ## Get/downloading PDF of an Invoice ** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-2": "Get or download the most recent PDF version of an invoice.", "0-0": "GET", "0-1": "/invoices/{id}/pdf", "h-3": "Accepted query params", "0-3": "- download, in:0|1" }, "cols": 4, "rows": 1 } [/block] ## Getting the Status of an Invoice ** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "GET", "0-1": "/invoices/{id}/status", "0-2": "Returns invoice status if it has not been paid or the payment_id if it has been paid." }, "cols": 3, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n\t\"status\": \"issued\"\n}", "language": "json", "name": "Response #1" }, { "code": "{\n\t\"razorpay_payment_id\": \"pay_jflajlga89hlJj\"\n}", "language": "json", "name": "Response #2" } ] } [/block] ## **Updating an Invoice** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "h-3": "Accepted attributes in request body", "0-0": "PATCH", "0-1": "/invoices/{id}", "0-2": "Updates an existing invoice", "0-3": "All validation rules apply as described above in [Request Body Attributes](#section--4-1-create-invoice-) section.\n- For invoice in **Draft** state:\n -sms_notify\n -email_notify\n -date\n -terms\n -notes\n -comment\n -receipt\n -view_less\n -source\n -type\n -customer\n -customer_id\n -line_items\n -amount\n -description\n -user_id\n -expire_by\n -draft\n- For invoice in **Issued** state:\n -terms\n -notes\n -comment\n -receipt" }, "cols": 4, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n\t\"line_items\": [\n\t {\n\t \"id\": \"li_7Nf9KyLyQVZDUS\",\n\t \"name\": \"Book / English August - Updated name and quantity\",\n\t \"quantity\": 5\n\t },\n\t {\n\t \"name\": \"Book / Elon Musk's Autobiography\",\n\t \"amount\": 25000,\n\t \"currency\": \"INR\",\n\t \"quantity\": 2\n\t }\n\t],\n\t\"notes\": {\n\t\t\"updated-key\": \"Updated Notes value\"\n\t}\n}", "language": "json", "name": "Request #1" }, { "code": "{\n \"id\": \"inv_7Nf9KwQdBsM2WH\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-n4\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n \"billing_address\": {\n \"id\": \"addr_7NZ3uUd4tI7RCF\",\n \"type\": \"billing_address\",\n \"primary\": true,\n \"line1\": \"#11, Navi Camp\",\n \"line2\": null,\n \"zipcode\": \"560076\",\n \"city\": \"Pandora\",\n \"state\": \"Karnataka\",\n \"country\": \"in\"\n }\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": null,\n \"line_items\": [\n {\n \"id\": \"li_7Nf9KyLyQVZDUS\",\n \"name\": \"Book / English August - Updated name and quantity\",\n \"description\": null,\n \"amount\": 20000,\n \"currency\": \"INR\",\n \"quantity\": 5\n },\n {\n \"id\": \"li_7NfBtHIo7uTAeh\",\n \"name\": \"Book / Elon Musk's Autobiography\",\n \"description\": null,\n \"amount\": 25000,\n \"currency\": \"INR\",\n \"quantity\": 2\n }\n ],\n \"payment_id\": null,\n \"status\": \"draft\",\n \"expire_by\": 1498439025,\n \"issued_at\": null,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"pending\",\n \"email_status\": \"pending\",\n \"date\": 1488439025,\n \"terms\": \"Terms and condition of the service/invoice\",\n \"amount\": 150000,\n \"description\": \"Just an optional description for the invoice\",\n \"notes\": {\n \"updated-key\": \"Updated Notes value\"\n },\n \"comment\": \"Optional comment to the customer for the invoice\",\n \"currency\": \"INR\",\n \"short_url\": null,\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488460744\n}", "language": "json", "name": "Response #1" }, { "code": "{\n\t\"terms\": \"Updated terms and conditions\",\n\t\"comment\": \"Updated comment for customer\"\n}", "language": "json", "name": "Request #2" }, { "code": "{\n \"id\": \"inv_7NbHv4vLbrvzPs\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-n2\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n \"billing_address\": {\n \"id\": \"addr_7NZ3uUd4tI7RCF\",\n \"type\": \"billing_address\",\n \"primary\": true,\n \"line1\": \"#11, Navi Camp\",\n \"line2\": null,\n \"zipcode\": \"560076\",\n \"city\": \"Pandora\",\n \"state\": \"Karnataka\",\n \"country\": \"in\"\n }\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7NbHv8f5jgYemg\",\n \"line_items\": [\n {\n \"id\": \"li_7NbHv7B3bD6sbK\",\n \"name\": \"Book / English August\",\n \"description\": null,\n \"amount\": 20000,\n \"currency\": \"INR\",\n \"quantity\": 2\n },\n {\n \"id\": \"li_7NbHv7l7YS4Wyb\",\n \"name\": \"Book / Ignited Minds\",\n \"description\": null,\n \"amount\": 15000,\n \"currency\": \"INR\",\n \"quantity\": 1\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1498439025,\n \"issued_at\": 1488447145,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"sent\",\n \"email_status\": \"sent\",\n \"date\": 1488439025,\n \"terms\": \"Updated terms and conditions\",\n \"amount\": 55000,\n \"description\": \"Just an optional description for the invoice\",\n \"notes\": {\n \"random_key\": \"Random note\"\n },\n \"comment\": \"Updated comment for customer\",\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/flui3ex\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488447145\n}", "language": "json", "name": "Response #2" } ] } [/block] Notes: - Invoice update is a patch request and `line_items` is treated as an attribute. So when you send line_items array, you would be adding a new line_items to an invoice. For example, in Request #1 - line_items with id `li_7Nf9KyLyQVZDUS` 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. - You can only send fields (as pointed above) which are allowed to be edited in given invoice state. Otherwise it will throw a bad request error. ## **Issuing an Invoice** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "POST", "0-1": "/invoices/{id}/issue", "0-2": "Issues an invoice in draft status. Short URL only gets created when the invoice is in issued state. Only then can the customer make the payment." }, "cols": 3, "rows": 1 } [/block] - It can only be called on an invoice that is in the draft state. - It's response is the invoice entity, similar to create/update API response. ## **Deleting an Invoice** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "DELETE", "0-1": "/invoices/{id}", "0-2": "Deletes an invoice which is in the draft status." }, "cols": 3, "rows": 1 } [/block] The response is always be an empty array, as shown below: [block:code] { "codes": [ { "code": "[]", "language": "json", "name": "Response" } ] } [/block] ## **Cancelling an Invoice** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "POST", "0-1": "/invoices/{id}/cancel", "0-2": "Cancels an unpaid invoice." }, "cols": 3, "rows": 1 } [/block] - It can only be called on an invoice that is not in the paid state. - It's response is the invoice entity, similar to create/update API response with `status` attribute's value as `cancelled`. # Webhooks We have a webhook `invoice.paid` which gets fired whenever an invoice is successfully paid by a customer. Every invoice is essentially linked to an order. So when a payment corresponding to an invoice is completed, you will receive both the `invoice.paid` webhook, as well as the `order.paid` webhook. If you are not using Orders API, you can disable `order.paid` webhook via the Dashboard. You can find more details about webhooks and `invoice.paid` event here: [https://docs.razorpay.com/v1/page/webhooks](https://docs.razorpay.com/v1/page/webhooks) [block:callout] { "type": "warning", "title": "Note", "body": "An early access program to complete invoicing feature is now available via the Dashboard. Drop us an email at support@razorpay.com to be a part of the program." } [/block]