Update an Invoice

Update the details of the Invoice using this endpoint.

PATCH /v1/invoices/:id

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X PATCH https://api.razorpay.com/v1/invoices/inv_DAtUWmR3Y5Dmxb \
-H 'content-type : application/json'
-d '{
  "line_items": [
    {
      "id": "li_DAweOizsysoJU6",
      "name": "Book / English August - Updated name and quantity",
      "quantity": 1
    },
    {
      "name": "Book / A Wild Sheep Chase",
      "amount": 200,
      "currency": "SGD",
      "quantity": 1
    }
  ],
  "notes": {
    "updated-key": "An updated note."
  }
}'

Success

{
  "id": "inv_DAtUWmR3Y5Dmxb",
  "entity": "invoice",
  "receipt": "#0961",
  "invoice_number": "#0961",
  "customer_id": "cust_DAtUWmvpktokrT",
  "customer_details": {
    "id": "cust_DAtUWmvpktokrT",
    "name": "<name>",
    "email": "<email>",
    "contact": "<phone>",
    "gstin": null,
    "billing_address": {
      "id": "addr_DAtUWoxgu91obl",
      "type": "billing_address",
      "primary": true,
      "line1": "Bakers Street",
      "line2": "T.P.S Road, Vazira, Borivali",
      "zipcode": "400092",
      "city": "Mumbai",
      "state": "Maharashtra",
      "country": "in"
    },
    "shipping_address": null,
    "customer_name": "<name>",
    "customer_email": "<email>",
    "customer_contact": "<phone>"
  },
  "order_id": null,
  "line_items": [
    {
      "id": "li_DAweOizsysoJU6",
      "item_id": null,
      "name": "Book / English August - Updated name and quantity",
      "description": "150 points in Quidditch",
      "amount": 400,
      "unit_amount": 400,
      "gross_amount": 400,
      "tax_amount": 0,
      "taxable_amount": 400,
      "net_amount": 400,
      "currency": "SGD",
      "type": "invoice",
      "tax_inclusive": false,
      "hsn_code": null,
      "sac_code": null,
      "tax_rate": null,
      "unit": null,
      "quantity": 1,
      "taxes": []
    },
    {
      "id": "li_DAwjWQUo07lnjF",
      "item_id": null,
      "name": "Book / A Wild Sheep Chase",
      "description": null,
      "amount": 200,
      "unit_amount": 200,
      "gross_amount": 200,
      "tax_amount": 0,
      "taxable_amount": 200,
      "net_amount": 200,
      "currency": "SGD",
      "type": "invoice",
      "tax_inclusive": false,
      "hsn_code": null,
      "sac_code": null,
      "tax_rate": null,
      "unit": null,
      "quantity": 1,
      "taxes": []
    }
  ],
  "payment_id": null,
  "status": "draft",
  "expire_by": 1567103399,
  "issued_at": null,
  "paid_at": null,
  "cancelled_at": null,
  "expired_at": null,
  "sms_status": null,
  "email_status": null,
  "date": 1566891149,
  "terms": null,
  "partial_payment": false,
  "gross_amount": 600,
  "tax_amount": 0,
  "taxable_amount": 600,
  "amount": 600,
  "amount_paid": null,
  "amount_due": null,
  "currency": "SGD",
  "currency_symbol": "<currency_symbol>",
  "description": "This is a test invoice.",
  "notes": {
    "updated-key": "An updated note."
  },
  "comment": null,
  "short_url": null,
  "view_less": true,
  "billing_start": null,
  "billing_end": null,
  "type": "invoice",
  "group_taxes_discounts": false,
  "created_at": 1566906474,
  "idempotency_key": null
}

Available in🇮🇳 India🇸🇬 Singapore🇺🇸 United States

Use this endpoint to update the details of the invoice.

The following table displays ths updates allowed as per invoice states:

Status	Parameter Update Allowed
Draft	All parameters can be updated including the line items. You can also add new line items.
Issued	You can update the following parameters: partial_payment receipt comment terms notes expire_by
Cancelled	Only notes can be updated.
Expired	Only notes can be updated.
Partially Paid	Only notes can be updated.
Paid	Only notes can be updated.

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X PATCH https://api.razorpay.com/v1/invoices/inv_DAtUWmR3Y5Dmxb \
-H 'content-type : application/json'
-d '{
  "line_items": [
    {
      "id": "li_DAweOizsysoJU6",
      "name": "Book / English August - Updated name and quantity",
      "quantity": 1
    },
    {
      "name": "Book / A Wild Sheep Chase",
      "amount": 200,
      "currency": "SGD",
      "quantity": 1
    }
  ],
  "notes": {
    "updated-key": "An updated note."
  }
}'

Success

{
  "id": "inv_DAtUWmR3Y5Dmxb",
  "entity": "invoice",
  "receipt": "#0961",
  "invoice_number": "#0961",
  "customer_id": "cust_DAtUWmvpktokrT",
  "customer_details": {
    "id": "cust_DAtUWmvpktokrT",
    "name": "<name>",
    "email": "<email>",
    "contact": "<phone>",
    "gstin": null,
    "billing_address": {
      "id": "addr_DAtUWoxgu91obl",
      "type": "billing_address",
      "primary": true,
      "line1": "Bakers Street",
      "line2": "T.P.S Road, Vazira, Borivali",
      "zipcode": "400092",
      "city": "Mumbai",
      "state": "Maharashtra",
      "country": "in"
    },
    "shipping_address": null,
    "customer_name": "<name>",
    "customer_email": "<email>",
    "customer_contact": "<phone>"
  },
  "order_id": null,
  "line_items": [
    {
      "id": "li_DAweOizsysoJU6",
      "item_id": null,
      "name": "Book / English August - Updated name and quantity",
      "description": "150 points in Quidditch",
      "amount": 400,
      "unit_amount": 400,
      "gross_amount": 400,
      "tax_amount": 0,
      "taxable_amount": 400,
      "net_amount": 400,
      "currency": "SGD",
      "type": "invoice",
      "tax_inclusive": false,
      "hsn_code": null,
      "sac_code": null,
      "tax_rate": null,
      "unit": null,
      "quantity": 1,
      "taxes": []
    },
    {
      "id": "li_DAwjWQUo07lnjF",
      "item_id": null,
      "name": "Book / A Wild Sheep Chase",
      "description": null,
      "amount": 200,
      "unit_amount": 200,
      "gross_amount": 200,
      "tax_amount": 0,
      "taxable_amount": 200,
      "net_amount": 200,
      "currency": "SGD",
      "type": "invoice",
      "tax_inclusive": false,
      "hsn_code": null,
      "sac_code": null,
      "tax_rate": null,
      "unit": null,
      "quantity": 1,
      "taxes": []
    }
  ],
  "payment_id": null,
  "status": "draft",
  "expire_by": 1567103399,
  "issued_at": null,
  "paid_at": null,
  "cancelled_at": null,
  "expired_at": null,
  "sms_status": null,
  "email_status": null,
  "date": 1566891149,
  "terms": null,
  "partial_payment": false,
  "gross_amount": 600,
  "tax_amount": 0,
  "taxable_amount": 600,
  "amount": 600,
  "amount_paid": null,
  "amount_due": null,
  "currency": "SGD",
  "currency_symbol": "<currency_symbol>",
  "description": "This is a test invoice.",
  "notes": {
    "updated-key": "An updated note."
  },
  "comment": null,
  "short_url": null,
  "view_less": true,
  "billing_start": null,
  "billing_end": null,
  "type": "invoice",
  "group_taxes_discounts": false,
  "created_at": 1566906474,
  "idempotency_key": null
}

Path Parameters

id · string · required

The unique identifier of the invoice.

Request Parameters

type · string

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

description · string

A brief description of the invoice.

draft · string

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

customer_id · string

You can pass the customer_id in this field, if you are using the Customers API. If not, you can pass the customer object described in the below fields.

customer · object

Customer details.

name · string · required

Customer’s name. Alphanumeric, with period (.), apostrophe (’) and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.

email · string

The customer’s email address. A maximum length of 64 characters. For example, [e-mail].

contact · string

The customer’s phone number. A maximum length of 15 characters including country code. For example, [phone].

billing_address · object

The customer’s billing address.

line1 · string · required

The first line of the customer’s address.

line2 · string

The second line of the customer’s address.

city · string · required

The city

zipcode · string · required

The zipcode

state · string · required

The state

country · string · required

The country

shipping_address · object

The customer’s shipping address.

line1 · string · required

The first line of the customer’s address.

line2 · string

The second line of the customer’s address.

city · string · required

The city

zipcode · string · required

The zipcode

state · string · required

The state

country · string · required

The country

line_items · object

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

item_id · string · required

If you are using the Items API, you may use an existing item. You can choose to override details such as name, description by passing these along with item_id. While the invoice will show the updated details, the existing item will not be updated. This parameter is mandatory if you are not going to use any other parameter in the array.

name · string · required

The item name. Mandatory if item_id is not provided.

description · string

A brief description of the item.

amount · integer · required

Amount to be paid using the invoice. Must be in the smallest unit of the currency. For example, if the amount to be received from the customer is ₹300, pass the value as 30000. Mandatory if item_id is not provided. In the case of three decimal currencies, such as KWD, BHD and OMR, to refund a payment of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, to refund a payment of 295, pass the value as 295.

Watch Out!

As per payment guidelines, you should pass the last decimal number as 0 for three decimal currency payments. For example, if you want to refund a customer 99.991 KD for a transaction, you should pass the value for the amount parameter as 99990 and not 99991.

currency · string

The currency associated with the item. Defaults to INR. Know about the list of supported international currencies. This should match invoice currency.

Handy Tips

Razorpay has added support for zero decimal currencies, such as JPY, and three decimal currencies, such as KWD, BHD, and OMR, allowing businesses to accept international payments in these currencies. Know more about Currency Conversion (May 2024).

quantity · integer

The number of units of the item billed in the invoice. Defaults to 1.

expire_by · integer

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

sms_notify · boolean

Defines who handles the SMS notification. Possible values:

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

email_notify · boolean

Defines who handles the email notification. Possible values:

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

partial_payment · boolean

Indicates whether the customer can make a partial payment on the invoice. Possible values:

• true: The customer can make partial payments.
• false (default): The customer cannot make partial payments.

currency · string

The currency associated with the invoice. You must mandatorily pass this parameter if accepting international payments. If you have passed currency as a sub-parameter in the line_item object, you must ensure that the same currency is passed in both places. Know about the list of supported international currencies.

Handy Tips

Razorpay has added support for zero decimal currencies, such as JPY, and three decimal currencies, such as KWD, BHD, and OMR, allowing businesses to accept international payments in these currencies. Know more about Currency Conversion (May 2024).

Response Parameters

id · string

The unique identifier of the invoice.

entity · string

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

type · string

Here, it should be invoice.

invoice_number · string

Unique number you added for internal reference. The minimum character length is 1 and maximum is 40.

customer_id · string

The unique identifier of the customer. You can create customer_id using the Customers API. Alternatively, you can pass the customer object described in the below fields.

customer_details · object

Details of the customer.

id · string

Unique identifier of the customer. For example, cust_1Aa00000000004.

name · string

Customer’s name. Alphanumeric, with period (.), apostrophe (’) and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.

email · string

The customer’s email address. A maximum length of 64 characters. For example, [e-mail].

contact · string

The customer’s phone number. A maximum length of 15 characters including country code. For example, [phone].

billing_address · object

Details of the customer’s billing address.

id · string

The unique identifier generated for the customer’s billing address.

type · string

The customer address type. Here it is billing_address.

primary · boolean

Defines if this is the primary address.

• true: It is the customer’s primary address.
• false: It is not the customer’s primary address.

line1 · string

The first line of the customer’s address.

line2 · string

The second line of the customer’s address.

city · string

The city.

zipcode · string

The zipcode.

state · string

The state.

country · string

The country.

shipping_address · object

Details of the customer’s shipping address.

id · string

The unique identifier generated for the customer’s shipping address.

type · string

The customer address type. Here it is shipping_address.

primary · boolean

Defines if this is the primary address.

• true: It is the customer’s primary address.
• false: It is not the customer’s primary address.

line1 · string

The first line of the customer’s address.

line2 · string

The second line of the customer’s address.

city · string

The city.

zipcode · string

The zipcode.

state · string

The state.

country · string

The country.

order_id · string

The unique identifier of the order associated with the invoice.

line_items · object

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

id · string

Unique identifier that is generated if a new item has been created while creating the invoice.

item_id · string

Unique identifier of the item generated using Items API that has been billed in the invoice.

name · string

The item’s name.

description · string

A brief description of the item.

amount · integer

The price of the item.

currency · string

The currency associated with the item. Default is INR. Know about the list of supported international currencies.

type · string

Here, it is invoice.

quantity · integer

The quantity of the item billed in the invoice. Defaults to 1.

payment_id · string

Unique identifier of a payment made against this invoice.

status · string

The status of the invoice. Know more about Invoice States. Possible values:

• draft
• issued
• partially_paid
• paid
• cancelled
• expired
• deleted

expire_by · integer

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

issued_at · integer

Timestamp, in Unix format, at which the invoice was issued to the customer.

paid_at · integer

Timestamp, in Unix format, at which the payment was made.

cancelled_at · integer

Timestamp, in Unix format, at which the invoice was cancelled.

expired_at · integer

Timestamp, in Unix format, at which the invoice expired.

sms_status · string

The delivery status of the SMS notification for the invoice sent to the customer. Possible values:

• pending
• sent

email_status · string

The delivery status of the email notification for the invoice sent to the customer. Possible values:

• pending
• sent

partial_payment · boolean

Indicates whether the customer can make a partial payment on the invoice. Possible values:

• true: The customer can make partial payments.
• false (default): The customer cannot make partial payments.

amount · integer

Amount to be paid using the invoice. Must be in the smallest unit of the currency. For example, if the amount to be received from the customer is , pass the value as 30000.

amount_paid · integer

Amount paid by the customer against the invoice.

amount_due · integer

The remaining amount to be paid by the customer for the issued invoice.

currency · string

The currency associated with the invoice. You must mandatorily pass this parameter if accepting international payments. If you have passed currency as a sub-parameter in the line_item object, you must ensure that the same currency is passed in both places. Know about the list of supported international currencies.

description · string

A brief description of the invoice. The maximum character length is 2048.

notes · object

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

short_url · string

The short URL that is generated. Share this link with customers to accept payments.

date · integer

Timestamp, in Unix format, that indicates the issue date of the invoice.

terms · string

Any terms to be included in the invoice. Maximum of 2048 characters.

comment · string

Any comments to be added in the invoice. Maximum of 2048 characters.

ref_num · string

A unique reference number for the invoice, used for internal tracking and reconciliation.

receipt · string

A unique receipt number that you can provide for the invoice, for your internal reference.

currency_symbol · string

For example, ₹.

idempotency_key · string

A unique key used to ensure idempotency of the invoice creation request, preventing duplicate invoices.

billing_end · integer

Unix timestamp marking the end of the billing period for the invoice.

gross_amount · integer

The gross amount for this invoice, in the smallest currency unit (paise for INR). For example, 50000.

subscription_id · string

Unique identifier of the subscription this invoice was generated for. null for one-off invoices.

Errors

The api key provided is invalid

Code: 400

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

Solution: Use and enter the correct API details while executing the API.

customer, line_items, sms_notify, email_notify, draft, date, currency is/are not required and should not be sent

Code: 400

The mentioned parameters are not required for updating an invoice. The API echoes the rejected field name in the response.

Solution: Pass only the required parameters in the Update Invoice API.

The amount field is required when item id is not present.

Code: 400

Only name is entered without item id or amount.

Solution: Provide either the item id or the amount with the name.

The name field is required when item id is not present.

Code: 400

Possible reasons:

• Only the amount field is entered without a name or item id.
• The amount, name or item id are not entered.

Solution: Provide the name field of the item when passing the amount.

amount cannot be updated if invoice has line_items.

Code: 400

The invoice already has one or more line_items. Razorpay derives the invoice amount from the line items, so a top-level amount cannot be updated independently.

Solution: Update the corresponding line_items[].amount instead, or remove the line items before changing the invoice amount.