{"__v":0,"_id":"57a9ba87d8e951170009c92c","initVersion":{"_id":"54dec8b6c2b4b70d009c3f0f","version":"1"},"project":"54c83b5aab706219009e067b","user":{"_id":"57a9b83fbfc4af2000270b81","username":"","name":"Prashanth YV"},"hidden":false,"createdAt":"2016-08-09T11:12:07.761Z","fullscreen":false,"htmlmode":false,"html":"","body":"This documents covers the entity details as well as the various operations available on the invoice entity.\nThis API is used to implement various features like:\n\n1. Link based payments\n2. eCOD\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Auth Required\",\n  \"body\": \"All the APIs listed below require basic authentication. The 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[/block]\n# Creating an Invoice\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"/v1/invoices\"\n}\n[/block]\nUse this API to create an invoice. You can also create a customer along with an invoice, using this API. It returns back an attribute **short_url** which you can send to your customer to pay for the invoice.\n\n## Request Entity\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"h-3\": \"Mandatory/ Optional\",\n    \"1-0\": \"customer\",\n    \"1-1\": \"object\",\n    \"1-2\": \"This object contains the customer details. Each field is explained below\",\n    \"1-3\": \"Optional\",\n    \"11-0\": \"date\",\n    \"11-1\": \"integer\",\n    \"11-2\": \"The invoice date. This should be an epoch timestamp.\",\n    \"11-3\": \"Optional.\\n**Default: Time of invoice creation**\",\n    \"12-0\": \"notes\",\n    \"12-1\": \"object\",\n    \"12-3\": \"Optional\",\n    \"12-2\": \"Key-Value store for storing reference fields for the merchant. This will not be used by Razorpay at all and is purely for storing data relevant to the merchant.\\nYou can find the documentation for notes [here](https://docs.razorpay.com/docs/notes).\",\n    \"15-0\": \"sms_notify\",\n    \"16-0\": \"email_notify\",\n    \"15-1\": \"boolean ('0'/'1')\",\n    \"16-1\": \"boolean ('0'/'1')\",\n    \"15-2\": \"If this is set to 1, the invoice link will be sent to the customer via SMS.\\nNote that the sms will not be sent if mobile number is not present for the given customer entity.\",\n    \"15-3\": \"Optional\\n**Default: 1**\",\n    \"16-2\": \"If this is set to 1, the invoice link will be sent to the customer via E-mail.\\nNote that the email will not be sent if email is not present for the given customer entity.\",\n    \"16-3\": \"Optional\\n**Default: 1**\",\n    \"10-0\": \"view_less\",\n    \"10-1\": \"boolean ('0'/'1')\",\n    \"10-2\": \"If this is set to `1`, the payment link will directly open a checkout, instead of an invoice.\\nIf this is set to `0`, the payment link will open an invoice, which will have a pay button which in turn opens a checkout form.\\n**Currently only `1` is supported for this attribute**\\n\\nFor eCOD and link based payments, this needs to be set to `1`\",\n    \"10-3\": \"Optional\\n**Default: 1**\",\n    \"5-0\": \"line_items\",\n    \"5-1\": \"array of objects\",\n    \"5-2\": \"This contains the list of items for which an invoice is created.\",\n    \"5-3\": \"Mandatory if amount is *not* being sent.\",\n    \"6-0\": \"line_items[][name]\",\n    \"7-0\": \"line_items[][description]\",\n    \"8-0\": \"line_items[][amount]\",\n    \"9-0\": \"line_items[][quantity]\",\n    \"6-1\": \"string\",\n    \"6-2\": \"Name of the item\",\n    \"6-3\": \"Mandatory if line_items object is being sent.\",\n    \"7-1\": \"string\",\n    \"7-2\": \"Description of the item\",\n    \"7-3\": \"Optional\",\n    \"8-1\": \"integer\",\n    \"8-2\": \"Amount of the item in paise.\",\n    \"8-3\": \"Mandatory if line_items object is being\",\n    \"9-1\": \"integer\",\n    \"9-2\": \"Quantity of the item.\",\n    \"9-3\": \"Optional\\n**Default: 1**\",\n    \"13-0\": \"currency\",\n    \"13-1\": \"string\",\n    \"13-2\": \"Currently, only INR is supported for this field.\",\n    \"13-3\": \"Mandatory\",\n    \"2-0\": \"customer[name]\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Name of the customer.\",\n    \"2-3\": \"Mandatory if customer object is being sent\",\n    \"3-0\": \"customer[contact]\",\n    \"3-1\": \"string\",\n    \"3-2\": \"Mobile number of the customer.\",\n    \"3-3\": \"Mandatory if customer object is being sent\",\n    \"4-0\": \"customer[email]\",\n    \"4-1\": \"string\",\n    \"4-2\": \"Email ID of the customer.\",\n    \"4-3\": \"Optional\",\n    \"0-0\": \"customer_id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"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    \"0-3\": \"Optional\",\n    \"14-0\": \"type\",\n    \"14-1\": \"stirng\",\n    \"14-3\": \"Mandatory\",\n    \"14-2\": \"Pass `ecod` if this invoice is going to be used for eCOD and `link` for link based payments.\",\n    \"17-0\": \"receipt\",\n    \"17-1\": \"string\",\n    \"17-3\": \"Optional\",\n    \"17-2\": \"This can be set to invoice number present in your system. This can help in identifying an invoice from an ID stored in your system.\\nNote that this should be **unique** across all your invoices.\"\n  },\n  \"cols\": 4,\n  \"rows\": 18\n}\n[/block]\n## Response Entity\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"string\",\n    \"1-0\": \"entity\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The value for this will always be \\\"invoice\\\"\",\n    \"2-0\": \"customer_id\",\n    \"2-1\": \"string\",\n    \"2-2\": \"The customer_id of the customer created or sent.\",\n    \"3-0\": \"order_id\",\n    \"3-1\": \"string\",\n    \"3-2\": \"We internally create an order for the invoice. This holds the ID of that order.\\nPlease refer to [Orders Documentation](https://docs.razorpay.com/v1/page/orders) for more information around Orders.\",\n    \"6-0\": \"status\",\n    \"6-1\": \"string\",\n    \"6-2\": \"The status of the invoice. When an invoice is created, the status will be in **issued** state. Once the customer pays for the invoice, it will be changed to **paid** status.\",\n    \"7-0\": \"sms_status\",\n    \"7-1\": \"string\",\n    \"7-2\": \"If you had set **sms_notify** as **`1`**, the status of the sms would be either **pending** or **sent**.\\nIf you had set **sms_notify** as **`0`**, this field will be **null**.\",\n    \"8-0\": \"email_status\",\n    \"8-1\": \"string\",\n    \"8-2\": \"If you had set **email_notify** as **`1`**, the status of the sms would be either **pending** or **sent**.\\nIf you had set **email_notify** as **`0`**, this field will be **null**.\",\n    \"9-0\": \"date\",\n    \"9-1\": \"integer\",\n    \"9-2\": \"The invoice date which you would have passed in the request.\",\n    \"10-0\": \"notes\",\n    \"10-1\": \"object\",\n    \"10-2\": \"Notes object passed by you in the request.\",\n    \"11-0\": \"short_url\",\n    \"11-1\": \"string\",\n    \"11-2\": \"This is the payment link which you need to send to your customer to receive the payment.\",\n    \"12-0\": \"view_less\",\n    \"12-1\": \"boolean\",\n    \"12-2\": \"Value of the view_less attribute sent in the request.\\nCurrently, we support only **`1`** for this.\",\n    \"15-0\": \"created_at\",\n    \"15-1\": \"integer\",\n    \"15-2\": \"The created at timestamp of the invoice.\",\n    \"4-0\": \"line_items\",\n    \"4-1\": \"array of objects\",\n    \"4-2\": \"Details of the line items which were sent in the request.\",\n    \"5-0\": \"customer_details\",\n    \"5-1\": \"object\",\n    \"5-2\": \"Details of the customer associated with the invoice.\",\n    \"14-0\": \"currency\",\n    \"14-1\": \"string\",\n    \"14-2\": \"Currently, only INR is supported.\",\n    \"13-0\": \"type\",\n    \"13-1\": \"string\",\n    \"13-2\": \"This will be `ecod` or `link` based on what type of invoice is being created.\",\n    \"0-2\": \"Unique ID of the invoice.\"\n  },\n  \"cols\": 3,\n  \"rows\": 16\n}\n[/block]\n## API Request/Response Samples\n\nNote the following points when creating an invoice\n- An invoice can be created with just an `amount` and a `description`.\n- `line_items` should not be sent if `amount` is being sent. `amount` will be calculated automatically from the `line_items`.\n- `description` and `line_items` can be sent together while creating an invoice.\n- An invoice must have either `line_items` or `amount` + `description`\n- If the `customer` has details which correspond to an existing customer in Razorpay, a new customer will not be created. The existing customer will be returned in the response.\n- `customer` and `customer_id` should not be sent as part of the same request. Only one of these should be sent. If you do not have a `customer_id` already, you can pass the customer details to create/get an existing customer.\n- Sending customer details is not mandatory to create an invoice. If customer details are not sent, `sms_notify` and `email_notify` fields are ignored and the communication will not be sent.\n- If the customer details are not sent during the creation of the invoice, invoice will get populated with email and contact number of the customer (retrieved from the payment data), if available, after the invoice is paid by the customer.\n- All boolean values should be string `0` or `1`. This is to ensure that there's consistency across various request content types.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"customer\\\": {\\n\\t\\t\\\"email\\\": \\\"test@razorpay.com\\\",\\n\\t\\t\\\"contact\\\": \\\"9999999999\\\",\\n\\t\\t\\\"name\\\": \\\"Test\\\"\\n\\t},\\n\\t\\\"line_items\\\": [{\\n\\t\\t\\\"quantity\\\": 1,\\n\\t\\t\\\"name\\\": \\\"Test item\\\",\\n\\t\\t\\\"description\\\": \\\"Test description\\\",\\n\\t\\t\\\"amount\\\": 100\\n\\t}, {\\n\\t\\t\\\"name\\\": \\\"Another test item\\\",\\n\\t\\t\\\"description\\\": \\\"Another test description\\\",\\n\\t\\t\\\"amount\\\": 1200\\n\\t}],\\n\\t\\\"date\\\": 1478531771,\\n\\t\\\"currency\\\": \\\"INR\\\",\\n\\t\\\"notes\\\": {\\n\\t\\t\\\"inv_num\\\": \\\"inv-101\\\"\\n\\t},\\n\\t\\\"sms_notify\\\": \\\"0\\\",\\n\\t\\\"email_notify\\\": \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request\"\n    },\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_6oYTsQyERkIDmk\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": null,\\n  \\\"customer_id\\\": \\\"cust_6oYGd5oISGJ1AK\\\",\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": \\\"Test\\\",\\n    \\\"customer_email\\\": \\\"test@razorpay.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_6oYTsagqpU3g07\\\",\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_6oYTsWyyECiYW9\\\",\\n      \\\"quantity\\\": 1,\\n      \\\"name\\\": \\\"Test item\\\",\\n      \\\"description\\\": \\\"Test description\\\",\\n      \\\"amount\\\": 100,\\n      \\\"currency\\\": \\\"INR\\\"\\n    },\\n    {\\n      \\\"id\\\": \\\"li_6oYTsYOrV27GXR\\\",\\n      \\\"quantity\\\": 1,\\n      \\\"name\\\": \\\"Another test item\\\",\\n      \\\"description\\\": \\\"Another test description\\\",\\n      \\\"amount\\\": 1200,\\n      \\\"currency\\\": \\\"INR\\\"\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"issued_at\\\": 1480795356,\\n  \\\"paid_at\\\": null,\\n  \\\"sms_status\\\": null,\\n  \\\"email_status\\\": \\\"sent\\\",\\n  \\\"date\\\": 1478531771,\\n  \\\"amount\\\": 1300,\\n  \\\"description\\\": null,\\n  \\\"notes\\\": {\\n    \\\"inv_num\\\": \\\"inv-101\\\"\\n  },\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://gimli.dev/phi9wx3\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": null,\\n  \\\"created_at\\\": 1480795356\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## Invoice status\n\nThe invoice `status` attribute values are explained below.\nPlease note that we are in the process of adding more statuses to the invoice.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"issued\",\n    \"1-0\": \"paid\",\n    \"0-1\": \"This is the default status of the invoice when it is created.\",\n    \"1-1\": \"This status is set when an invoice is paid by the customer.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Webhook\",\n  \"body\": \"We have a webhook `invoice.paid` which gets fired whenever an invoice is successfully paid by a customer.\\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}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Customers API\",\n  \"body\": \"Instead of passing customer details each time, you can also use the Customers API for all CRUD operations on this entity. If you use this API you can simply pass the `customer_id` as an alternative for the `customer` field. The details for this API are available here: [https://docs.razorpay.com/v1/page/customers-api](https://docs.razorpay.com/v1/page/customers-api)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"eCOD/ Link Based Payments\",\n  \"body\": \"For eCOD and Link Based Payments, you need to pass the following fields mandatorily:\\n\\n- `type: ecod` or `type: link` - as applicable\\n- `view_less: 1`\\n\\nWithout these fields, there's no guarantee of the functionality working as described.\"\n}\n[/block]\n# Fetching Invoices\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"/invoices\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Params\",\n    \"h-1\": \"Mandatory/Optional\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"from\",\n    \"1-0\": \"to\",\n    \"2-0\": \"count\",\n    \"3-0\": \"skip\",\n    \"4-0\": \"receipt\",\n    \"0-1\": \"Optional\",\n    \"1-1\": \"Optional\",\n    \"2-1\": \"Optional\",\n    \"3-1\": \"Optional\",\n    \"4-1\": \"Optional\",\n    \"0-2\": \"Timestamp from when the invoices are to be fetched.\",\n    \"1-2\": \"Timestamp up till when invoices are to be fetched.\",\n    \"2-2\": \"Count of invoices to be fetched.\\n**Default: 10 | Max: 100**\",\n    \"3-2\": \"Numbers of invoices to be skipped.\\n**Default: 0**\",\n    \"4-2\": \"Invoices with the provided value for receipt.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"entity\\\": \\\"collection\\\",\\n  \\\"count\\\": 2,\\n  \\\"items\\\": [\\n    {\\n      \\\"id\\\": \\\"inv_6oYGd3JloGcu2W\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": null,\\n      \\\"customer_id\\\": \\\"cust_6oYGd5oISGJ1AK\\\",\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": \\\"Test\\\",\\n        \\\"customer_email\\\": \\\"test@razorpay.com\\\",\\n        \\\"customer_contact\\\": \\\"9999999999\\\",\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": \\\"order_6oYGdEVrMu80nL\\\",\\n      \\\"line_items\\\": [\\n        {\\n          \\\"id\\\": \\\"li_6oYGdBe3xICoQM\\\",\\n          \\\"quantity\\\": 1,\\n          \\\"name\\\": \\\"Test item\\\",\\n          \\\"description\\\": \\\"Test description\\\",\\n          \\\"amount\\\": 100,\\n          \\\"currency\\\": \\\"INR\\\"\\n        }\\n      ],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"issued\\\",\\n      \\\"issued_at\\\": 1480794604,\\n      \\\"paid_at\\\": null,\\n      \\\"sms_status\\\": null,\\n      \\\"email_status\\\": \\\"sent\\\",\\n      \\\"date\\\": 1478531771,\\n      \\\"amount\\\": 100,\\n      \\\"description\\\": null,\\n      \\\"notes\\\": {\\n        \\\"inv_num\\\": \\\"inv-101\\\"\\n      },\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://gimli.dev/7osaxml\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": null,\\n      \\\"created_at\\\": 1480794604\\n    },\\n    {\\n      \\\"id\\\": \\\"inv_6oY5wq8lkOfMKx\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": null,\\n      \\\"customer_id\\\": null,\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": null,\\n        \\\"customer_email\\\": null,\\n        \\\"customer_contact\\\": null,\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": \\\"order_6oY5ws4hEOFKJH\\\",\\n      \\\"line_items\\\": [],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"issued\\\",\\n      \\\"issued_at\\\": 1480793997,\\n      \\\"paid_at\\\": null,\\n      \\\"sms_status\\\": null,\\n      \\\"email_status\\\": null,\\n      \\\"date\\\": null,\\n      \\\"amount\\\": 100,\\n      \\\"description\\\": \\\"Abc def\\\",\\n      \\\"notes\\\": [],\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://gimli.dev/2qertk9\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": null,\\n      \\\"created_at\\\": 1480793997\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n# Fetching an invoice by id\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"/invoices/{invoice_id}\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_6oYGd3JloGcu2W\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": null,\\n  \\\"customer_id\\\": \\\"cust_6oYGd5oISGJ1AK\\\",\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": \\\"Test\\\",\\n    \\\"customer_email\\\": \\\"test@razorpay.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_6oYGdEVrMu80nL\\\",\\n  \\\"line_items\\\": [\\n    {\\n      \\\"id\\\": \\\"li_6oYGdBe3xICoQM\\\",\\n      \\\"quantity\\\": 1,\\n      \\\"name\\\": \\\"Test item\\\",\\n      \\\"description\\\": \\\"Test description\\\",\\n      \\\"amount\\\": 100,\\n      \\\"currency\\\": \\\"INR\\\"\\n    }\\n  ],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"issued_at\\\": 1480794604,\\n  \\\"paid_at\\\": null,\\n  \\\"sms_status\\\": null,\\n  \\\"email_status\\\": \\\"sent\\\",\\n  \\\"date\\\": 1478531771,\\n  \\\"amount\\\": 100,\\n  \\\"description\\\": null,\\n  \\\"notes\\\": {\\n    \\\"inv_num\\\": \\\"inv-101\\\"\\n  },\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://gimli.dev/7osaxml\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": null,\\n  \\\"created_at\\\": 1480794604\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]","slug":"invoices","title":"Invoices"}

Invoices


This documents covers the entity details as well as the various operations available on the invoice entity. This API is used to implement various features like: 1. Link based payments 2. eCOD [block:callout] { "type": "info", "title": "Auth Required", "body": "All the APIs listed below require basic authentication. The 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." } [/block] # Creating an Invoice [block:api-header] { "type": "post", "title": "/v1/invoices" } [/block] Use this API to create an invoice. You can also create a customer along with an invoice, using this API. It returns back an attribute **short_url** which you can send to your customer to pay for the invoice. ## Request Entity [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Type", "h-2": "Description", "h-3": "Mandatory/ Optional", "1-0": "customer", "1-1": "object", "1-2": "This object contains the customer details. Each field is explained below", "1-3": "Optional", "11-0": "date", "11-1": "integer", "11-2": "The invoice date. This should be an epoch timestamp.", "11-3": "Optional.\n**Default: Time of invoice creation**", "12-0": "notes", "12-1": "object", "12-3": "Optional", "12-2": "Key-Value store for storing reference fields for the merchant. This will not be used by Razorpay at all and is purely for storing data relevant to the merchant.\nYou can find the documentation for notes [here](https://docs.razorpay.com/docs/notes).", "15-0": "sms_notify", "16-0": "email_notify", "15-1": "boolean ('0'/'1')", "16-1": "boolean ('0'/'1')", "15-2": "If this is set to 1, the invoice link will be sent to the customer via SMS.\nNote that the sms will not be sent if mobile number is not present for the given customer entity.", "15-3": "Optional\n**Default: 1**", "16-2": "If this is set to 1, the invoice link will be sent to the customer via E-mail.\nNote that the email will not be sent if email is not present for the given customer entity.", "16-3": "Optional\n**Default: 1**", "10-0": "view_less", "10-1": "boolean ('0'/'1')", "10-2": "If this is set to `1`, the payment link will directly open a checkout, instead of an invoice.\nIf this is set to `0`, the payment link will open an invoice, which will have a pay button which in turn opens a checkout form.\n**Currently only `1` is supported for this attribute**\n\nFor eCOD and link based payments, this needs to be set to `1`", "10-3": "Optional\n**Default: 1**", "5-0": "line_items", "5-1": "array of objects", "5-2": "This contains the list of items for which an invoice is created.", "5-3": "Mandatory if amount is *not* being sent.", "6-0": "line_items[][name]", "7-0": "line_items[][description]", "8-0": "line_items[][amount]", "9-0": "line_items[][quantity]", "6-1": "string", "6-2": "Name of the item", "6-3": "Mandatory if line_items object is being sent.", "7-1": "string", "7-2": "Description of the item", "7-3": "Optional", "8-1": "integer", "8-2": "Amount of the item in paise.", "8-3": "Mandatory if line_items object is being", "9-1": "integer", "9-2": "Quantity of the item.", "9-3": "Optional\n**Default: 1**", "13-0": "currency", "13-1": "string", "13-2": "Currently, only INR is supported for this field.", "13-3": "Mandatory", "2-0": "customer[name]", "2-1": "string", "2-2": "Name of the customer.", "2-3": "Mandatory if customer object is being sent", "3-0": "customer[contact]", "3-1": "string", "3-2": "Mobile number of the customer.", "3-3": "Mandatory if customer object is being sent", "4-0": "customer[email]", "4-1": "string", "4-2": "Email ID of the customer.", "4-3": "Optional", "0-0": "customer_id", "0-1": "string", "0-2": "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", "0-3": "Optional", "14-0": "type", "14-1": "stirng", "14-3": "Mandatory", "14-2": "Pass `ecod` if this invoice is going to be used for eCOD and `link` for link based payments.", "17-0": "receipt", "17-1": "string", "17-3": "Optional", "17-2": "This can be set to invoice number present in your system. This can help in identifying an invoice from an ID stored in your system.\nNote that this should be **unique** across all your invoices." }, "cols": 4, "rows": 18 } [/block] ## Response Entity [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Type", "h-2": "Description", "0-0": "id", "0-1": "string", "1-0": "entity", "1-1": "string", "1-2": "The value for this will always be \"invoice\"", "2-0": "customer_id", "2-1": "string", "2-2": "The customer_id of the customer created or sent.", "3-0": "order_id", "3-1": "string", "3-2": "We internally create an order for the invoice. This holds the ID of that order.\nPlease refer to [Orders Documentation](https://docs.razorpay.com/v1/page/orders) for more information around Orders.", "6-0": "status", "6-1": "string", "6-2": "The status of the invoice. When an invoice is created, the status will be in **issued** state. Once the customer pays for the invoice, it will be changed to **paid** status.", "7-0": "sms_status", "7-1": "string", "7-2": "If you had set **sms_notify** as **`1`**, the status of the sms would be either **pending** or **sent**.\nIf you had set **sms_notify** as **`0`**, this field will be **null**.", "8-0": "email_status", "8-1": "string", "8-2": "If you had set **email_notify** as **`1`**, the status of the sms would be either **pending** or **sent**.\nIf you had set **email_notify** as **`0`**, this field will be **null**.", "9-0": "date", "9-1": "integer", "9-2": "The invoice date which you would have passed in the request.", "10-0": "notes", "10-1": "object", "10-2": "Notes object passed by you in the request.", "11-0": "short_url", "11-1": "string", "11-2": "This is the payment link which you need to send to your customer to receive the payment.", "12-0": "view_less", "12-1": "boolean", "12-2": "Value of the view_less attribute sent in the request.\nCurrently, we support only **`1`** for this.", "15-0": "created_at", "15-1": "integer", "15-2": "The created at timestamp of the invoice.", "4-0": "line_items", "4-1": "array of objects", "4-2": "Details of the line items which were sent in the request.", "5-0": "customer_details", "5-1": "object", "5-2": "Details of the customer associated with the invoice.", "14-0": "currency", "14-1": "string", "14-2": "Currently, only INR is supported.", "13-0": "type", "13-1": "string", "13-2": "This will be `ecod` or `link` based on what type of invoice is being created.", "0-2": "Unique ID of the invoice." }, "cols": 3, "rows": 16 } [/block] ## API Request/Response Samples Note the following points when creating an invoice - An invoice can be created with just an `amount` and a `description`. - `line_items` should not be sent if `amount` is being sent. `amount` will be calculated automatically from the `line_items`. - `description` and `line_items` can be sent together while creating an invoice. - An invoice must have either `line_items` or `amount` + `description` - If the `customer` has details which correspond to an existing customer in Razorpay, a new customer will not be created. The existing customer will be returned in the response. - `customer` and `customer_id` should not be sent as part of the same request. Only one of these should be sent. If you do not have a `customer_id` already, you can pass the customer details to create/get an existing customer. - Sending customer details is not mandatory to create an invoice. If customer details are not sent, `sms_notify` and `email_notify` fields are ignored and the communication will not be sent. - If the customer details are not sent during the creation of the invoice, invoice will get populated with email and contact number of the customer (retrieved from the payment data), if available, after the invoice is paid by the customer. - All boolean values should be string `0` or `1`. This is to ensure that there's consistency across various request content types. [block:code] { "codes": [ { "code": "{\n\t\"customer\": {\n\t\t\"email\": \"test@razorpay.com\",\n\t\t\"contact\": \"9999999999\",\n\t\t\"name\": \"Test\"\n\t},\n\t\"line_items\": [{\n\t\t\"quantity\": 1,\n\t\t\"name\": \"Test item\",\n\t\t\"description\": \"Test description\",\n\t\t\"amount\": 100\n\t}, {\n\t\t\"name\": \"Another test item\",\n\t\t\"description\": \"Another test description\",\n\t\t\"amount\": 1200\n\t}],\n\t\"date\": 1478531771,\n\t\"currency\": \"INR\",\n\t\"notes\": {\n\t\t\"inv_num\": \"inv-101\"\n\t},\n\t\"sms_notify\": \"0\",\n\t\"email_notify\": \"1\"\n}", "language": "json", "name": "Request" }, { "code": "{\n \"id\": \"inv_6oYTsQyERkIDmk\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_6oYGd5oISGJ1AK\",\n \"customer_details\": {\n \"customer_name\": \"Test\",\n \"customer_email\": \"test@razorpay.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_6oYTsagqpU3g07\",\n \"line_items\": [\n {\n \"id\": \"li_6oYTsWyyECiYW9\",\n \"quantity\": 1,\n \"name\": \"Test item\",\n \"description\": \"Test description\",\n \"amount\": 100,\n \"currency\": \"INR\"\n },\n {\n \"id\": \"li_6oYTsYOrV27GXR\",\n \"quantity\": 1,\n \"name\": \"Another test item\",\n \"description\": \"Another test description\",\n \"amount\": 1200,\n \"currency\": \"INR\"\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"issued_at\": 1480795356,\n \"paid_at\": null,\n \"sms_status\": null,\n \"email_status\": \"sent\",\n \"date\": 1478531771,\n \"amount\": 1300,\n \"description\": null,\n \"notes\": {\n \"inv_num\": \"inv-101\"\n },\n \"currency\": \"INR\",\n \"short_url\": \"http://gimli.dev/phi9wx3\",\n \"view_less\": true,\n \"type\": null,\n \"created_at\": 1480795356\n}", "language": "json", "name": "Response" } ] } [/block] ## Invoice status The invoice `status` attribute values are explained below. Please note that we are in the process of adding more statuses to the invoice. [block:parameters] { "data": { "h-0": "Status", "h-1": "Description", "0-0": "issued", "1-0": "paid", "0-1": "This is the default status of the invoice when it is created.", "1-1": "This status is set when an invoice is paid by the customer." }, "cols": 2, "rows": 2 } [/block] [block:callout] { "type": "info", "title": "Webhook", "body": "We have a webhook `invoice.paid` which gets fired whenever an invoice is successfully paid by a customer.\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)" } [/block] [block:callout] { "type": "info", "title": "Customers API", "body": "Instead of passing customer details each time, you can also use the Customers API for all CRUD operations on this entity. If you use this API you can simply pass the `customer_id` as an alternative for the `customer` field. The details for this API are available here: [https://docs.razorpay.com/v1/page/customers-api](https://docs.razorpay.com/v1/page/customers-api)" } [/block] [block:callout] { "type": "warning", "title": "eCOD/ Link Based Payments", "body": "For eCOD and Link Based Payments, you need to pass the following fields mandatorily:\n\n- `type: ecod` or `type: link` - as applicable\n- `view_less: 1`\n\nWithout these fields, there's no guarantee of the functionality working as described." } [/block] # Fetching Invoices [block:api-header] { "type": "get", "title": "/invoices" } [/block] [block:parameters] { "data": { "h-0": "Params", "h-1": "Mandatory/Optional", "h-2": "Description", "0-0": "from", "1-0": "to", "2-0": "count", "3-0": "skip", "4-0": "receipt", "0-1": "Optional", "1-1": "Optional", "2-1": "Optional", "3-1": "Optional", "4-1": "Optional", "0-2": "Timestamp from when the invoices are to be fetched.", "1-2": "Timestamp up till when invoices are to be fetched.", "2-2": "Count of invoices to be fetched.\n**Default: 10 | Max: 100**", "3-2": "Numbers of invoices to be skipped.\n**Default: 0**", "4-2": "Invoices with the provided value for receipt." }, "cols": 3, "rows": 5 } [/block] [block:code] { "codes": [ { "code": "{\n \"entity\": \"collection\",\n \"count\": 2,\n \"items\": [\n {\n \"id\": \"inv_6oYGd3JloGcu2W\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_6oYGd5oISGJ1AK\",\n \"customer_details\": {\n \"customer_name\": \"Test\",\n \"customer_email\": \"test@razorpay.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_6oYGdEVrMu80nL\",\n \"line_items\": [\n {\n \"id\": \"li_6oYGdBe3xICoQM\",\n \"quantity\": 1,\n \"name\": \"Test item\",\n \"description\": \"Test description\",\n \"amount\": 100,\n \"currency\": \"INR\"\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"issued_at\": 1480794604,\n \"paid_at\": null,\n \"sms_status\": null,\n \"email_status\": \"sent\",\n \"date\": 1478531771,\n \"amount\": 100,\n \"description\": null,\n \"notes\": {\n \"inv_num\": \"inv-101\"\n },\n \"currency\": \"INR\",\n \"short_url\": \"http://gimli.dev/7osaxml\",\n \"view_less\": true,\n \"type\": null,\n \"created_at\": 1480794604\n },\n {\n \"id\": \"inv_6oY5wq8lkOfMKx\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": null,\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": null,\n \"customer_contact\": null,\n \"customer_address\": null\n },\n \"order_id\": \"order_6oY5ws4hEOFKJH\",\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"issued_at\": 1480793997,\n \"paid_at\": null,\n \"sms_status\": null,\n \"email_status\": null,\n \"date\": null,\n \"amount\": 100,\n \"description\": \"Abc def\",\n \"notes\": [],\n \"currency\": \"INR\",\n \"short_url\": \"http://gimli.dev/2qertk9\",\n \"view_less\": true,\n \"type\": null,\n \"created_at\": 1480793997\n }\n ]\n}", "language": "json", "name": "Response" } ] } [/block] # Fetching an invoice by id [block:api-header] { "type": "get", "title": "/invoices/{invoice_id}" } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"inv_6oYGd3JloGcu2W\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_6oYGd5oISGJ1AK\",\n \"customer_details\": {\n \"customer_name\": \"Test\",\n \"customer_email\": \"test@razorpay.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_6oYGdEVrMu80nL\",\n \"line_items\": [\n {\n \"id\": \"li_6oYGdBe3xICoQM\",\n \"quantity\": 1,\n \"name\": \"Test item\",\n \"description\": \"Test description\",\n \"amount\": 100,\n \"currency\": \"INR\"\n }\n ],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"issued_at\": 1480794604,\n \"paid_at\": null,\n \"sms_status\": null,\n \"email_status\": \"sent\",\n \"date\": 1478531771,\n \"amount\": 100,\n \"description\": null,\n \"notes\": {\n \"inv_num\": \"inv-101\"\n },\n \"currency\": \"INR\",\n \"short_url\": \"http://gimli.dev/7osaxml\",\n \"view_less\": true,\n \"type\": null,\n \"created_at\": 1480794604\n}", "language": "json", "name": "Response" } ] } [/block]