INinvoiceninja
invoices

Update invoice

Changed on

PUT /api/v1/invoices/{id}

Handles the updating of an invoice by id.

Triggered actions are available when updating or creating an invoice.
These are query parameters that can be chained in order to perform additional actions on the entity, these include:

?send_email=true [Saves and sends the invoice]
?mark_sent=true [Saves and marks the invoice as sent]
?paid=true [Saves and marks the invoice as paid]
?amount_paid=100 [Saves and marks the invoice as paid with the given amount]
?cancel=true [Saves and marks the invoice as cancelled]
?save_default_footer=true [Saves the current footer as the default footer]
?save_default_terms=true [Saves the current terms as the default terms]
?retry_e_send=true [Saves and retries the e-send for the invoice]
?redirect=https://example.com [Saves and redirects to the given url]
put/api/v1/invoices/{id}

Request

Path parameters

idstring string required

The Invoice Hashed ID

Query parameters

includestring
Example:first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

Headers

X-API-TOKENstring required
Example:TOKEN

The API token to be used for authentication

X-Requested-Withstring required
Example:XMLHttpRequest

Used to send the XMLHttpRequest header

Response

Returns the invoice object

idstring

The invoice hashed id

user_idstring

The user hashed id

assigned_user_idstring

The assigned user hashed id

client_idstring

The client hashed id

status_idstring

The invoice status variable

numberstring

The invoice number - is a unique alpha numeric number per invoice per company

po_numberstring

The purchase order associated with this invoice

termsstring

The invoice terms

public_notesstring

The public notes of the invoice

private_notesstring

The private notes of the invoice

footerstring

The invoice footer notes

custom_value1string

A custom field value

custom_value2string

A custom field value

custom_value3string

A custom field value

custom_value4string

A custom field value

tax_name1string

The tax name

tax_name2string

The tax name

tax_rate1number float

The tax rate

tax_rate2number float

The tax rate

tax_name3string

The tax name

tax_rate3number float

The tax rate

total_taxesnumber float

The total taxes for the invoice

amountnumber float

The invoice amount

balancenumber float

The invoice balance

paid_to_datenumber float

The amount paid on the invoice to date

discountnumber float

The invoice discount, can be an amount or a percentage

partialnumber float

The deposit/partial amount

is_amount_discountboolean

Flag determining if the discount is an amount or a percentage

is_deletedboolean

Defines if the invoice has been deleted

uses_inclusive_taxesboolean

Defines the type of taxes used as either inclusive or exclusive

datestring date

The Invoice Date

last_sent_datestring date

The last date the invoice was sent out

next_send_datestring date

The Next date for a reminder to be sent

partial_due_datestring date

The due date for the deposit/partial amount

due_datestring date

The due date of the invoice

last_viewednumber

Timestamp

updated_atnumber

Timestamp

archived_atnumber

Timestamp

custom_surcharge1number float

First Custom Surcharge

custom_surcharge2number float

Second Custom Surcharge

custom_surcharge3number float

Third Custom Surcharge

custom_surcharge4number float

Fourth Custom Surcharge

custom_surcharge_tax1boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax2boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax3boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax4boolean

Toggles charging taxes on custom surcharge amounts

project_idstring

The project associated with this invoice

auto_bill_triesinteger

The number of times the invoice has attempted to be auto billed

auto_bill_enabledboolean

Boolean flag determining if the invoice is set to auto bill

subscription_idstring

The subscription associated with this invoice

location_idstring

The client location id that this invoice relates to

design_idstring

The unique identifier of the design template used for this invoice

e_invoiceobject

E-invoice configuration and data

exchange_ratenumber float

The exchange rate used for currency conversion

vendor_idstring

The unique identifier of the vendor associated with this invoice

Example response

{
  "id": "Opnel5aKBz",
  "user_id": "Opnel5aKBz",
  "assigned_user_id": "Opnel5aKBz",
  "client_id": "Opnel5aKBz",
  "status_id": "4",
  "number": "INV_101",
  "po_number": "PO-1234",
  "terms": "These are invoice terms",
  "public_notes": "These are some public notes",
  "private_notes": "These are some private notes",
  "custom_value1": "2022-10-01",
  "custom_value2": "Something custom",
  "tax_rate1": 10,
  "tax_rate2": 10,
  "tax_rate3": 10,
  "total_taxes": 10,
  "line_items": [
    {
      "quantity": 1,
      "cost": 10,
      "product_key": "Product key",
      "tags": "Retail,Priority Customer",
      "product_cost": 10,
      "notes": "Item notes",
      "discount": 5,
      "tax_name1": "GST",
      "tax_rate1": 10,
      "tax_name2": "VAT",
      "tax_rate2": 5,
      "tax_name3": "CA Sales Tax",
      "tax_rate3": 3,
      "sort_id": "0",
      "line_total": 10,
      "gross_line_total": 15,
      "tax_amount": 1,
      "custom_value1": "Custom value 1",
      "custom_value2": "Custom value 2",
      "custom_value3": "Custom value 3",
      "custom_value4": "Custom value 4",
      "type_id": "1",
      "tax_id": "1"
    }
  ],
  "invitations": [
    {
      "id": "Opnel5aKBz",
      "client_contact_id": "Opnel5aKBz",
      "key": "Opnel5aKBz4343343566236gvbb",
      "link": "https://www.example.com/invitations/Opnel5aKBz4343343566236gvbb",
      "updated_at": 1434342123,
      "archived_at": 1434342123,
      "email_error": "The email error"
    }
  ],
  "amount": 10,
  "balance": 10,
  "paid_to_date": 10,
  "discount": 10,
  "partial": 10,
  "is_amount_discount": true,
  "is_deleted": true,
  "uses_inclusive_taxes": true,
  "date": "1994-07-30",
  "last_sent_date": "1994-07-30",
  "next_send_date": "1994-07-30",
  "partial_due_date": "1994-07-30",
  "due_date": "1994-07-30",
  "last_viewed": 1434342123,
  "updated_at": 1434342123,
  "archived_at": 1434342123,
  "custom_surcharge1": 10,
  "custom_surcharge2": 10,
  "custom_surcharge3": 10,
  "custom_surcharge4": 10,
  "custom_surcharge_tax1": true,
  "custom_surcharge_tax2": true,
  "custom_surcharge_tax3": true,
  "custom_surcharge_tax4": true,
  "project_id": "Opnel5aKBz",
  "auto_bill_tries": 1,
  "auto_bill_enabled": true,
  "subscription_id": "Opnel5aKBz",
  "location_id": "Opnel5aKBz",
  "design_id": "Opnel5aKBz",
  "exchange_rate": 1,
  "vendor_id": "Opnel5aKBz"
}

Changes