Top

Invoices

List invoices
GET /invoices
List all invoices with pagination.
Get an invoice
GET /invoices/:invoice_id
Get the details of an invoice.
Create an invoice
POST /invoices
Create an invoice for your customer.
Update an invoice
PUT /invoices/:invoice_id
Update an existing invoice. To delete a line item just remove it from the line_items list.
Delete an invoice
DELETE /invoices/:invoice_id
Delete an existing invoice. Invoices which have payment or credits note applied cannot be deleted.
Mark an invoice as sent
POST /invoices/:invoice_id/status/sent
Mark a draft invoice as sent.
Void an invoice
POST /invoices/:invoice_id/status/void
Mark an invoice status as void. Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits.
Mark as draft
POST /invoices/:invoice_id/status/draft
Mark a voided invoice as draft.
Email an invoice
POST /invoices/:invoice_id/email
Email an invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
Email invoices
POST /invoices/email
Send invoices to your customers by email. Maximum of 10 invoices can be sent at once.
Get invoice email content
GET /invoices/:invoice_id/email
Get the email content of an invoice.
Remind customer
POST /invoices/:invoice_id/paymentreminder
Remind your customer about an unpaid invoice by email. Reminder will be sent, only for the invoices which are in open or overdue status.
Bulk invoice reminder
POST /invoices/paymentreminder
Remind your customer about an unpaid invoices by email. Reminder mail will be send, only for the invoices is in open or overdue status. Maximum 10 invoices can be reminded at once.
Get payment reminder mail content
GET /invoices/:invoice_id/paymentreminder
Get the mail content of the payment reminder.
Bulk export invoices
GET /invoices/pdf
Maximum of 25 invoices can be exported in a single pdf.
Bulk print invoices
GET /invoices/print
Export invoices as pdf and print them. Maximum of 25 invoices can be printed.
Disable payment reminder
POST /invoices/:invoice_id/paymentreminder/disable
Disable automated payment reminders for an invoice.
Enable payment reminder
POST /invoices/:invoice_id/paymentreminder/enable
Enable automated payment reminders for an invoice.
Write off invoice
POST /invoices/:invoice_id/writeoff
Write off the invoice balance amount of an invoice.
Cancel write off
POST /invoices/:invoiceid/writeoff/cancel
Cancel the write off amount of an invoice.
Update billing address
PUT /invoices/:invoice_id/address/billing
Updates the billing address for this invoice alone. You can set this address as default billing address for your customer by specifying 'is_update_customer' param as true.
Update shipping address
PUT /invoices/:invoice_id/address/shipping
Updates the shipping address for this invoice. You can set this address as default shipping address for your customer by specifying 'is_update_customer' param as true.
List invoice templates
GET /invoices/templates
Get all invoice pdf templates.
Update invoice template
PUT /invoices/:invoice_id/templates/:template_id
Update the pdf template associated with the invoice.

List invoices

GET  /invoices

List all invoices with pagination.

Parameters

invoice_number string
[100]
Search invoices by invoice number.
Variants: invoice_number_startswith and invoice_number_contains
item_name string
[100]
Search invoices by item name.
Variants: item_name_startswith and item_name_contains
item_id string Search invoices by item id.
item_description string
[100]
Search invoices by item description.
Variants: item_description_startswith and item_description_contains
reference_number string
[100]
Search invoices by invoice reference number (i.e., P.O.#).
Variants: reference_number_startswith and reference_number_contains
customer_name string
[100]
Search invoices by customer name.
Variants: customer_name_startswith and customer_name_contains
recurring_invoice_id string Search invoices by recurring profile id.
email string
[100]
Search invoices by customer contact persons email.
total double Search invoices by invoice total.
Variants: total_less_than, total_less_equals, total_greater_than and total_greater_equals
balance double Search invoices by invoice total.
Variants: balance_less_than, balance_less_equals, balance_greater_than and balance_greater_equals
custom_field string Search invoices by custom fields.
Variants: custom_field_startswith and custom_field_contains
date string
[yyyy-mm-dd]
Search invoices by invoice date. Default date format is yyyy-mm-dd.
Variants: date_start, date_end, date_before and date_after
due_date string
[yyyy-mm-dd]
Search invoices by due date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after
status string Search invoices by invoice status.
Allowed Values: sent, draft, overdue, paid, void, unpaid, partiallypaid and viewed
customer_id string Search invoices by customer id.
filter_by string Filter invoices by any status or payment expected date.
Allowed Values: Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate
search_text string
[100]
Search invoices by invoice number or purchase order or customer name.
sort_column string Sort invoices.
Allowed Values: customer_name, invoice_number, date, due_date, total, balance and created_time

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "invoices": [
    {
      "invoice_id": "982000000567114",
      "customer_name": "Bowman & Co",
      "customer_id": "982000000567001",
      "status": "draft",
      "invoice_number": "INV-00003",
      "reference_number": "",
      "date": "2013-11-17",
      "due_date": "2013-12-03",
      "due_days": "Due in 14 day(s)",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "total": 40.60,
      "balance": 40.60,
      "created_time": "2013-11-18T02:31:51-0800",
      "is_emailed": false,
      "reminders_sent": 0,
      "payment_expected_date": "",
      "last_payment_date": ""
    },
    {
      "invoice_id": "982000000567082",
      "customer_name": "Bowman & Co",
      "customer_id": "982000000567001",
      "status": "draft",
      "invoice_number": "INV-00002",
      "reference_number": "",
      "date": "2013-11-17",
      "due_date": "2013-12-03",
      "due_days": "Due in 14 day(s)",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "total": 36.47,
      "balance": 36.47,
      "created_time": "2013-11-18T02:19:55-0800",
      "is_emailed": false,
      "reminders_sent": 0,
      "payment_expected_date": "",
      "last_payment_date": ""
    },
    {
      "invoice_id": "982000000567036",
      "customer_name": "Bowman & Co",
      "customer_id": "982000000567001",
      "status": "partially_paid",
      "invoice_number": "INV-00001",
      "reference_number": "",
      "date": "2013-11-17",
      "due_date": "2013-12-03",
      "due_days": "Due in 14 day(s)",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "total": 153.00,
      "balance": 103.66,
      "created_time": "2013-11-18T02:13:38-0800",
      "is_emailed": false,
      "reminders_sent": 0,
      "payment_expected_date": "",
      "last_payment_date": "2013-11-17"
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Invoices",
    "applied_filter": "Status.All",
    "sort_column": "created_time",
    "sort_order": "D"
  }
}

Get an invoice

GET  /invoices/:invoice_id

Get the details of an invoice.

Parameters

print boolean Print the exported pdf.
accept string Get the details of a particular invoice in formats such as json/ pdf/ html. Default format is json.
Allowed Values: json, pdf and html

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "invoice": {
    "invoice_id": "982000000567036",
    "invoice_number": "INV-00001",
    "date": "2013-11-18",
    "status": "partially_paid",
    "payment_terms": 15,
    "payment_terms_label": "Net 15",
    "due_date": "2013-12-03",
    "payment_expected_date": "",
    "last_payment_date": "2013-11-18",
    "reference_number": "",
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "contact_persons": [
      "982000000567003",
      "982000000567005"
    ],
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "discount": 0.00,
    "is_discount_before_tax": true,
    "discount_type": "item_level",
    "recurring_invoice_id": "",
    "line_items": [
      {
        "line_item_id": "982000000567044",
        "item_id": "982000000030049",
        "project_id": "",
        "time_entry_ids": "",
        "expense_id": "",
        "expense_receipt_name": "",
        "name": "Hard Drive",
        "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
        "item_order": 1,
        "bcy_rate": 120.00,
        "rate": 120.00,
        "quantity": 1.00,
        "unit": "",
        "discount_amount": 0.00,
        "discount": 0.00,
        "tax_id": "",
        "tax_name": "",
        "tax_type": "tax",
        "tax_percentage": 0,
        "item_total": 120.00
      },
      {
        "line_item_id": "982000000567046",
        "item_id": "982000000030051",
        "project_id": "",
        "time_entry_ids": "",
        "expense_id": "",
        "expense_receipt_name": "",
        "name": "Premium Plan - Web hosting",
        "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
        "item_order": 2,
        "bcy_rate": 33.00,
        "rate": 33.00,
        "quantity": 1.00,
        "unit": "",
        "discount_amount": 0.00,
        "discount": 0.00,
        "tax_id": "",
        "tax_name": "",
        "tax_type": "tax",
        "tax_percentage": 0,
        "item_total": 33.00
      }
    ],
    "shipping_charge": 0.00,
    "adjustment": 0.00,
    "adjustment_description": "",
    "sub_total": 153.00,
    "tax_total": 0.00,
    "total": 153.00,
    "taxes": [],
    "payment_reminder_enabled": true,
    "payment_made": 26.91,
    "credits_applied": 22.43,
    "tax_amount_withheld": 0.00,
    "balance": 103.66,
    "write_off_amount": 0.00,
    "allow_partial_payments": true,
    "price_precision": 2,
    "payment_options": {
      "payment_gateways": [
        {
          "configured": true,
          "additional_field1": "standard",
          "gateway_name": "paypal"
        },
        {
          "configured": true,
          "gateway_name": "authorize_net"
        },
        {
          "configured": true,
          "gateway_name": "stripe"
        }
      ]
    },
    "is_emailed": false,
    "reminders_sent": 0,
    "last_reminder_sent_date": "",
    "billing_address": {
      "address": "4141 Hacienda Drive",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "shipping_address": {
      "address": "Suite 125, McMillan Avenue",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94134",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "notes": "Thanks for your business.",
    "terms": "Terms and conditions apply",
    "custom_fields": [
      {
        "index": 1,
        "show_on_pdf": false,
        "value": "15 Dec 2013",
        "label": "Delivery Date"
      },
      {
        "index": 2,
        "show_on_pdf": false,
        "value": "0.99$/Day",
        "label": "Late Charge"
      },
      {
        "index": 3,
        "show_on_pdf": false,
        "value": "John David",
        "label": "Reporter"
      }
    ],
    "template_id": "982000000000107",
    "template_name": "Service - Classic",
    "created_time": "2013-11-18T02:13:38-0800",
    "last_modified_time": "2013-11-18T02:38:18-0800",
    "attachment_name": "",
    "can_send_in_mail": true,
    "salesperson_id": "",
    "salesperson_name": "",
    "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea"      
  }
}

Create an invoice

POST  /invoices

Create an invoice for your customer.

Parameters

send boolean Send the invoice to the contact person(s) associated with the invoice.
Allowed Values: true and false
ignore_auto_number_generation boolean Ignore auto invoice number generation for this invoice. This mandates the invoice number.
Allowed Values: true and false

Request attributes

customer_id* string ID of the customer the invoice has to be created.
contact_persons array Array of contact person(s) for whom invoice has to be sent.
invoice_number string
[50]
Mandatory if auto number generation is disabled.
template_id string ID of the pdf template associated with the invoice.
date string
[yyyy-mm-dd]
The date the invoice is created.
payment_terms string
[100]
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this.
payment_terms_label string
[100]
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days".
due_date string
[yyyy-mm-dd]
Date invoice is due.
discount string
[100]
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
is_discount_before_tax boolean Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type string How the discount is specified. Allowed values are entity_level or item_level.
Allowed Values: entity_level and item_level
exchange_rate double Exchange rate of the currency.
recurring_invoice_id string ID of the recurring invoice from which the invoice is created.
invoiced_estimate_id string ID of the estimate from which the invoice is created.
salesperson_name string
[200]
Name of the sales person.
custom_fields array Custom fields for an invoice.
line_items array Line items of an invoice.
item_id string ID of the item.
project_id string ID of the Project associated with the line item.
expense_id string ID of the expense which is invoiced.
name string
[100]
Name of the line item.
description string
[2000]
Description of the line item.
rate double Rate of the line item.
unit string
[100]
Unit of the line item e.g. kgs, Nos.
quantity double Quantity of the line item.
discount string
[100]
Discount applied to the line item. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id string ID of the tax or tax group applied to the line item.
time_entry_ids array IDs of the time entries associated with the project.
payment_options hash Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
payment_gateways array Online payment gateways through which payment can be made.
gateway_name string Name of the payment gateway associated with the invoice. E.g. paypal, stripe.
Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
additional_field1 string Paypal payment method.
Allowed Values: standard and adaptive
allow_partial_payments boolean Can the payment be made partially for this invoice.
shipping_charge string
[100]
Shipping charges applied to the invoice.
adjustment double Adjustments made to the invoice.
adjustment_description string
[200]
Customize the adjustment description. E.g. Rounding off.

Sample Request

{
      "customer_id": "982000000567001",
      "contact_persons": [
        "982000000567003",
        "982000000567005"
      ],
      "invoice_number": "INV-00001",
      "reference_number": "",
      "template_id": "982000000000107",
      "date": "2013-11-18",
      "payment_terms": 15,
      "payment_terms_label": "Net 15",
      "due_date": "2013-12-03",
      "discount": 0.00,
      "is_discount_before_tax": true,
      "discount_type": "item_level",
      "exchange_rate": 1.00,
      "recurring_invoice_id": "",
      "invoiced_estimate_id": "",
      "salesperson_name": "",
      "custom_fields": [
        {
          "index": 1,
          "value": "15 Dec 2013"
        },
        {
          "index": 2,
          "value": "0.99$/Day"
        },
        {
          "index": 3,
          "value": "John David"
        }
      ],
      "line_items": [
        {
          "item_id": "982000000030049",
          "project_id": "",
          "expense_id": "",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "item_order": 1,
          "rate": 120.00,
          "unit": "",
          "quantity": 1.00,
          "discount": 0.00,
          "tax_id": ""
        },
        {
          "item_id": "982000000030051",
          "project_id": "",
          "expense_id": "",
          "name": "Premium Plan - Web hosting",
          "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
          "item_order": 2,
          "rate": 33.00,
          "unit": "",
          "quantity": 1.00,
          "discount": 0.00,
          "tax_id": ""
        }
      ],
      "payment_options": {
        "payment_gateways": [
          {
            "gateway_name": "paypal",
            "additional_field1": "standard"
          },
          {
            "gateway_name": "authorize_net",
            "additional_field1": ""
          },
          {
            "gateway_name": "stripe",
            "additional_field1": ""
          }
        ]
      },
      "allow_partial_payments": true,
      "custom_body": "",
      "custom_subject": "",
      "notes": "Thanks for your business.",
      "terms": "Terms and conditions apply",
      "shipping_charge": 0.00,
      "adjustment": 0.00,
      "adjustment_description": "",
      "reason": ""
    }

Sample Response


Status: 201 Created
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The invoice has been created.",
      "invoice": {
        "invoice_id": "982000000567036",
        "invoice_number": "INV-00001",
        "date": "2013-11-18",
        "status": "partially_paid",
        "payment_terms": 15,
        "payment_terms_label": "Net 15",
        "due_date": "2013-12-03",
        "payment_expected_date": "",
        "last_payment_date": "2013-11-18",
        "reference_number": "",
        "customer_id": "982000000567001",
        "customer_name": "Bowman & Co",
        "contact_persons": [
          "982000000567003",
          "982000000567005"
        ],
        "currency_id": "982000000000190",
        "currency_code": "USD",
        "exchange_rate": 1.00,
        "discount": 0.00,
        "is_discount_before_tax": true,
        "discount_type": "item_level",
        "recurring_invoice_id": "",
        "line_items": [
          {
            "line_item_id": "982000000567044",
            "item_id": "982000000030049",
            "project_id": "",
            "time_entry_ids": "",
            "expense_id": "",
            "expense_receipt_name": "",
            "name": "Hard Drive",
            "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
            "item_order": 1,
            "bcy_rate": 120.00,
            "rate": 120.00,
            "quantity": 1.00,
            "unit": "",
            "discount_amount": 0.00,
            "discount": 0.00,
            "tax_id": "",
            "tax_name": "",
            "tax_type": "tax",
            "tax_percentage": 0,
            "item_total": 120.00
          },
          {
            "line_item_id": "982000000567046",
            "item_id": "982000000030051",
            "project_id": "",
            "time_entry_ids": "",
            "expense_id": "",
            "expense_receipt_name": "",
            "name": "Premium Plan - Web hosting",
            "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
            "item_order": 2,
            "bcy_rate": 33.00,
            "rate": 33.00,
            "quantity": 1.00,
            "unit": "",
            "discount_amount": 0.00,
            "discount": 0.00,
            "tax_id": "",
            "tax_name": "",
            "tax_type": "tax",
            "tax_percentage": 0,
            "item_total": 33.00
          }
        ],
        "shipping_charge": 0.00,
        "adjustment": 0.00,
        "adjustment_description": "",
        "sub_total": 153.00,
        "tax_total": 0.00,
        "total": 153.00,
        "taxes": [],
        "payment_reminder_enabled": true,
        "payment_made": 26.91,
        "credits_applied": 22.43,
        "tax_amount_withheld": 0.00,
        "balance": 103.66,
        "write_off_amount": 0.00,
        "allow_partial_payments": true,
        "price_precision": 2,
        "payment_options": {
          "payment_gateways": [
            {
              "configured": true,
              "additional_field1": "standard",
              "gateway_name": "paypal"
            },
            {
              "configured": true,
              "gateway_name": "authorize_net"
            },
            {
              "configured": true,
              "gateway_name": "stripe"
            }
          ]
        },
        "is_emailed": false,
        "reminders_sent": 0,
        "last_reminder_sent_date": "",
        "billing_address": {
          "address": "4141 Hacienda Drive",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "shipping_address": {
          "address": "Suite 125, McMillan Avenue",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94134",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "notes": "Thanks for your business.",
        "terms": "Terms and conditions apply",
        "custom_fields": [
          {
            "index": 1,
            "show_on_pdf": false,
            "value": "15 Dec 2013",
            "label": "Delivery Date"
          },
          {
            "index": 2,
            "show_on_pdf": false,
            "value": "0.99$/Day",
            "label": "Late Charge"
          },
          {
            "index": 3,
            "show_on_pdf": false,
            "value": "John David",
            "label": "Reporter"
          }
        ],
        "template_id": "982000000000107",
        "template_name": "Service - Classic",
        "created_time": "2013-11-18T02:13:38-0800",
        "last_modified_time": "2013-11-18T02:38:18-0800",
        "attachment_name": "",
        "can_send_in_mail": true,
        "salesperson_id": "",
        "salesperson_name": ""
      }
    }

Update an invoice

PUT  /invoices/:invoice_id

Update an existing invoice. To delete a line item just remove it from the line_items list.

Parameters

ignore_auto_number_generation boolean Ignore auto estimate number generation for this estimate. This mandates the estimate number.

Request attributes

customer_id* string ID of the customer the invoice has to be created.
contact_persons array Array of contact person(s) for whom invoice has to be sent.
invoice_number string
[50]
Mandatory if auto number generation is disabled.
template_id string ID of the pdf template associated with the invoice.
date string
[yyyy-mm-dd]
The date the invoice is created.
payment_terms string
[100]
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this.
payment_terms_label string
[100]
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days".
due_date string
[yyyy-mm-dd]
Date invoice is due.
discount string
[100]
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
is_discount_before_tax boolean Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type string How the discount is specified. Allowed values are entity_level or item_level.
Allowed Values: entity_level and item_level
exchange_rate double Exchange rate of the currency.
recurring_invoice_id string ID of the recurring invoice from which the invoice is created.
salesperson_name string
[200]
Name of the sales person.
custom_fields array Custom fields for an invoice.
line_items array Line items of an invoice.
item_id string ID of the item.
line_item_id string ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
project_id string ID of the Project associated with the line item.
expense_id string ID of the expense which is invoiced.
name string
[100]
Name of the line item.
description string
[2000]
Description of the line item.
rate double Rate of the line item.
unit string
[100]
Unit of the line item e.g. kgs, Nos.
quantity double Quantity of the line item.
discount string
[100]
Discount applied to the line item. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id string ID of the tax or tax group applied to the line item.
time_entry_ids array IDs of the time entries associated with the project.
payment_options hash Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
payment_gateways array Online payment gateways through which payment can be made.
gateway_name string Name of the payment gateway associated with the invoice. E.g. paypal, stripe.
Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
additional_field1 string Paypal payment method.
Allowed Values: standard and adaptive
allow_partial_payments boolean Can the payment be made partially for this invoice.
shipping_charge string
[100]
Shipping charges applied to the invoice.
adjustment double Adjustments made to the invoice.
adjustment_description string
[200]
Customize the adjustment description. E.g. Rounding off.

Sample Request

{
      "customer_id": "982000000567001",
      "contact_persons": [
        "982000000567003",
        "982000000567005"
      ],
      "invoice_number": "INV-00001",
      "reference_number": "",
      "template_id": "982000000000107",
      "date": "2013-11-18",
      "payment_terms": 15,
      "payment_terms_label": "Net 15",
      "due_date": "2013-12-03",
      "discount": 0.00,
      "is_discount_before_tax": true,
      "discount_type": "item_level",
      "exchange_rate": 1.00,
      "recurring_invoice_id": "",
      "invoiced_estimate_id": "",
      "salesperson_name": "",
      "custom_fields": [
        {
          "index": 1,
          "value": "15 Dec 2013"
        },
        {
          "index": 2,
          "value": "0.99$/Day"
        },
        {
          "index": 3,
          "value": "John David"
        }
      ],
      "line_items": [
        {
          "item_id": "982000000030049",
          "line_item_id": "982000000567044",
          "project_id": "",
          "expense_id": "",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "item_order": 1,
          "rate": 120.00,
          "unit": "",
          "quantity": 1.00,
          "discount": 0.00,
          "tax_id": ""
        },
        {
          "item_id": "982000000030051",
          "line_item_id": "982000000567046",
          "project_id": "",
          "expense_id": "",
          "name": "Premium Plan - Web hosting",
          "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
          "item_order": 2,
          "rate": 33.00,
          "unit": "",
          "quantity": 1.00,
          "discount": 0.00,
          "tax_id": ""
        }
      ],
      "payment_options": {
        "payment_gateways": [
          {
            "gateway_name": "paypal",
            "additional_field1": "standard"
          },
          {
            "gateway_name": "authorize_net",
            "additional_field1": ""
          },
          {
            "gateway_name": "stripe",
            "additional_field1": ""
          }
        ]
      },
      "allow_partial_payments": true,
      "custom_body": "",
      "custom_subject": "",
      "notes": "Thanks for your business.",
      "terms": "Terms and conditions apply",
      "shipping_charge": 0.00,
      "adjustment": 0.00,
      "adjustment_description": "",
      "reason": ""
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Invoice information has been updated.",
      "invoice": {
        "invoice_id": "982000000567036",
        "invoice_number": "INV-00001",
        "date": "2013-11-18",
        "status": "partially_paid",
        "payment_terms": 15,
        "payment_terms_label": "Net 15",
        "due_date": "2013-12-03",
        "payment_expected_date": "",
        "last_payment_date": "2013-11-18",
        "reference_number": "",
        "customer_id": "982000000567001",
        "customer_name": "Bowman & Co",
        "contact_persons": [
          "982000000567003",
          "982000000567005"
        ],
        "currency_id": "982000000000190",
        "currency_code": "USD",
        "exchange_rate": 1.00,
        "discount": 0.00,
        "is_discount_before_tax": true,
        "discount_type": "item_level",
        "recurring_invoice_id": "",
        "line_items": [
          {
            "line_item_id": "982000000567044",
            "item_id": "982000000030049",
            "project_id": "",
            "time_entry_ids": "",
            "expense_id": "",
            "expense_receipt_name": "",
            "name": "Hard Drive",
            "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
            "item_order": 1,
            "bcy_rate": 120.00,
            "rate": 120.00,
            "quantity": 1.00,
            "unit": "",
            "discount_amount": 0.00,
            "discount": 0.00,
            "tax_id": "",
            "tax_name": "",
            "tax_type": "tax",
            "tax_percentage": 0,
            "item_total": 120.00
          },
          {
            "line_item_id": "982000000567046",
            "item_id": "982000000030051",
            "project_id": "",
            "time_entry_ids": "",
            "expense_id": "",
            "expense_receipt_name": "",
            "name": "Premium Plan - Web hosting",
            "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
            "item_order": 2,
            "bcy_rate": 33.00,
            "rate": 33.00,
            "quantity": 1.00,
            "unit": "",
            "discount_amount": 0.00,
            "discount": 0.00,
            "tax_id": "",
            "tax_name": "",
            "tax_type": "tax",
            "tax_percentage": 0,
            "item_total": 33.00
          }
        ],
        "shipping_charge": 0.00,
        "adjustment": 0.00,
        "adjustment_description": "",
        "sub_total": 153.00,
        "tax_total": 0.00,
        "total": 153.00,
        "taxes": [],
        "payment_reminder_enabled": true,
        "payment_made": 26.91,
        "credits_applied": 22.43,
        "tax_amount_withheld": 0.00,
        "balance": 103.66,
        "write_off_amount": 0.00,
        "allow_partial_payments": true,
        "price_precision": 2,
        "payment_options": {
          "payment_gateways": [
            {
              "configured": true,
              "additional_field1": "standard",
              "gateway_name": "paypal"
            },
            {
              "configured": true,
              "gateway_name": "authorize_net"
            },
            {
              "configured": true,
              "gateway_name": "stripe"
            }
          ]
        },
        "is_emailed": false,
        "reminders_sent": 0,
        "last_reminder_sent_date": "",
        "billing_address": {
          "address": "4141 Hacienda Drive",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "shipping_address": {
          "address": "Suite 125, McMillan Avenue",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94134",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "notes": "Thanks for your business.",
        "terms": "Terms and conditions apply",
        "custom_fields": [
          {
            "index": 1,
            "show_on_pdf": false,
            "value": "15 Dec 2013",
            "label": "Delivery Date"
          },
          {
            "index": 2,
            "show_on_pdf": false,
            "value": "0.99$/Day",
            "label": "Late Charge"
          },
          {
            "index": 3,
            "show_on_pdf": false,
            "value": "John David",
            "label": "Reporter"
          }
        ],
        "template_id": "982000000000107",
        "template_name": "Service - Classic",
        "created_time": "2013-11-18T02:13:38-0800",
        "last_modified_time": "2013-11-18T02:38:18-0800",
        "attachment_name": "",
        "can_send_in_mail": true,
        "salesperson_id": "",
        "salesperson_name": ""
      }
    }

Delete an invoice

DELETE  /invoices/:invoice_id

Delete an existing invoice. Invoices which have payment or credits note applied cannot be deleted.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The invoice has been deleted."
}

Mark an invoice as sent

POST  /invoices/:invoice_id/status/sent

Mark a draft invoice as sent.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Invoice status has been changed to Sent."
}

Void an invoice

POST  /invoices/:invoice_id/status/void

Mark an invoice status as void. Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Invoice status has been changed to Void."
}

Mark as draft

POST  /invoices/:invoice_id/status/draft

Mark a voided invoice as draft.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Status of invoice changed from void to draft."
}

Email an invoice

POST  /invoices/:invoice_id/email

Email an invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.

Parameters

send_customer_statement boolean Send customer statement pdf a with email.
send_attachment boolean Send the invoice attachment a with the email.

multipart/form-data

attachments file The files to be attached with the email.

Request attributes

send_from_org_email_id boolean Boolean to trigger the email from the organization's email address.
to_mail_ids* array Array of email address of the recipients.
cc_mail_ids array Array of email address of the recipients to be cced.

Sample Request

{
          "to_mail_ids": [
            "willsmith@bowmanfurniture.com"
          ],
          "cc_mail_ids": [
            "peterparker@bowmanfurniture.com"
          ],
          "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)",
          "body": "Dear Customer,         <br><br><br><br>Thanks for your business.         <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc  >pay online for this invoice.</a>         <br><br>Here's an overview of the invoice for your reference.         <br><br><br><br>Invoice Overview:         <br><br>Invoice # : INV-00001         <br><br>Date : 05 Aug 2013         <br><br>Amount : $541.82         <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\nRegards<br>\nZillium Inc<br>\n",
          "send_from_org_email_id": true,
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Your invoice has been sent."
}

Email invoices

POST  /invoices/email

Send invoices to your customers by email. Maximum of 10 invoices can be sent at once.

Parameters

invoice_ids* string
[100]
Comma separated invoice ids which are to be emailed.

Request attributes

contacts array Contacts for whom email or snail mail has to be sent.
contact_id* string ID of the contact. Can specify if email or snail mail has to be sent for each contact.

Sample Request

{
          "contacts": [
                {
                  "contact_id": "460000000026049",
                  "email": true,
                  "snail_mail": false
                }
           ]
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Mission accomplished! We've sent all the invoices."
}

Get invoice email content

GET  /invoices/:invoice_id/email

Get the email content of an invoice.

Parameters

email_template_id string Get the email content based on a specific email template. If this param is not inputted, then the content will be based on the email template associated with the customer. If no template is associated with the customer, then default template will be used.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "data": {
    "gateways_configured": true,
    "deprecated_placeholders_used": [],
    "body": "Dear Customer,         <br><br>Thanks for your business.         <br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice3.localzoho.com:443/SecurePayment?CInvoiceID=381e6a2f9f6022afb6d5e1f6a68f4326548bf703be129216bb8e7c7ff2c98ac12e889a17a9ab3233eb38d61b2993f449  >pay online for this invoice.</a>         <br>Here's an overview of the invoice for your reference.         <br><br>Invoice Overview:         <br>Invoice # : INV-00001         <br>Date : 18 Nov 2013         <br>Amount : $153.00         <br><br>It was great working with you. Looking forward to working with you again.<br><br><br>Regards<br>Zillium Inc<br>",
    "error_list": [],
    "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)",
    "emailtemplates": [
      {
        "selected": true,
        "name": "Default",
        "email_template_id": "982000000000067"
      }
    ],
    "to_contacts": [
      {
        "first_name": "Will",
        "selected": true,
        "phone": "+1-925-921-9201",
        "email": "willsmith@bowmanfurniture.com",
        "last_name": "Smith",
        "salutation": "Mr.",
        "contact_person_id": "982000000567003",
        "mobile": "+1-4054439562"
      },
      {
        "first_name": "Peter",
        "selected": true,
        "phone": "+1-925-929-7211",
        "email": "peterparker@bowmanfurniture.com",
        "last_name": "Parker",
        "salutation": "Mr.",
        "contact_person_id": "982000000567005",
        "mobile": "+1-4054439760"
      }
    ],
    "attachment_name": "",
    "file_name": "INV-00001.pdf",
    "from_emails": [
      {
        "user_name": "John Smith",
        "selected": true,
        "email": "johnsmith@zilliuminc.com"
      },
      {
        "user_name": "John David",
        "selected": false,
        "email": "johndavid@zilliuminc.com"
      }
    ],
    "customer_id": "982000000567001"
  }
}

Remind customer

POST  /invoices/:invoice_id/paymentreminder

Remind your customer about an unpaid invoice by email. Reminder will be sent, only for the invoices which are in open or overdue status.

Parameters

send_customer_statement boolean Send customer statement pdf a with payment reminder.

multipart/form-data

attachments file The files to be attached with the payment reminder.

Request attributes

send_from_org_email_id boolean Boolean to trigger the email from the organization's email address.
to_mail_ids* array Array of email address of the recipients.
cc_mail_ids array Array of email address of the recipients to be cced.

Sample Request

{
          "to_mail_ids": [
            "willsmith@bowmanfurniture.com"
          ],
          "cc_mail_ids": [
            "peterparker@bowmanfurniture.com"
          ],
          "subject": "Payment Reminder for Invoice#: INV-00001",
          "body": "Dear Customer,\r\n\r\nMay we remind you that the invoice INV-00001 issued on 05 Aug 2013 is overdue by 45 days. If you have already paid for this invoice, accept our apologies and ignore this reminder. We have attached the invoice for your reference.         \r\n\r\nPay online for this invoice by following this <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b931463bf4c102a564b8805f1ac4011d0342e24  >link</a>.         \r\n\r\nFeel free to get in touch with us for any clarifications. Thanks in advance for the payment.<br><br><br>\nRegards<br>\nZillium Inc<br>\n",
          "send_from_org_email_id": "",
        }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Your payment reminder has been sent."
}

Bulk invoice reminder

POST  /invoices/paymentreminder

Remind your customer about an unpaid invoices by email. Reminder mail will be send, only for the invoices is in open or overdue status. Maximum 10 invoices can be reminded at once.

Parameters

invoice_ids* string
[100]
Array of invoice ids for which the reminder has to be sent.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Success! All reminders have been sent."
}

Get payment reminder mail content

GET  /invoices/:invoice_id/paymentreminder

Get the mail content of the payment reminder.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "data": {
    "gateways_configured": true,
    "deprecated_placeholders_used": [],
    "body": "Dear Customer,         <br><br>May we remind you that the invoice INV-00001 issued on 18 Nov 2013 is due for payment. If you have already paid for this invoice, accept our apologies and ignore this reminder. We have attached the invoice for your reference.         <br><br>To pay online for this invoice <a href= https://invoice3.localzoho.com:443/SecurePayment?CInvoiceID=381e6a2f9f6022afb6d5e1f6a68f4326548bf703be129216bb8e7c7ff2c98ac12e889a17a9ab3233dc5c9774f008e02a  >click here</a>.         <br><br>Feel free to get in touch with us for any clarifications. Thanks in advance for the payment.<br><br><br>Regards<br>Zillium Inc<br>",
    "error_list": [],
    "subject": "Payment Reminder for Invoice#: INV-00001",
    "to_contacts": [
      {
        "first_name": "Will",
        "selected": false,
        "phone": "+1-925-921-9201",
        "email": "willsmith@bowmanfurniture.com",
        "last_name": "Smith",
        "salutation": "Mr.",
        "contact_person_id": "982000000567003",
        "mobile": "+1-4054439562"
      },
      {
        "first_name": "Peter",
        "selected": false,
        "phone": "+1-925-929-7211",
        "email": "peterparker@bowmanfurniture.com",
        "last_name": "Parker",
        "salutation": "Mr.",
        "contact_person_id": "982000000567005",
        "mobile": "+1-4054439760"
      }
    ],
    "attachment_name": "",
    "file_name": "INV-00001.pdf",
    "from_emails": [
      {
        "user_name": "John Smith",
        "selected": true,
        "email": "johnsmith@zilliuminc.com"
      },
      {
        "user_name": "John David",
        "selected": false,
        "email": "johndavid@zilliuminc.com"
      }
    ],
    "customer_id": "982000000567001"
  }
}

Bulk export invoices

GET  /invoices/pdf

Maximum of 25 invoices can be exported in a single pdf.

Parameters

invoice_ids* string
[100]
Comma separated invoice ids which are to be export as pdf.

Bulk print invoices

GET  /invoices/print

Export invoices as pdf and print them. Maximum of 25 invoices can be printed.

Parameters

invoice_ids* string
[100]
Comma separated invoice ids which are to be printed.

Disable payment reminder

POST  /invoices/:invoice_id/paymentreminder/disable

Disable automated payment reminders for an invoice.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Reminders stopped."
}

Enable payment reminder

POST  /invoices/:invoice_id/paymentreminder/enable

Enable automated payment reminders for an invoice.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Reminders enabled."
}

Write off invoice

POST  /invoices/:invoice_id/writeoff

Write off the invoice balance amount of an invoice.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Invoice has been written off."
}

Cancel write off

POST  /invoices/:invoiceid/writeoff/cancel

Cancel the write off amount of an invoice.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The write off done for this invoice has been cancelled."
}

Update billing address

PUT  /invoices/:invoice_id/address/billing

Updates the billing address for this invoice alone. You can set this address as default billing address for your customer by specifying 'is_update_customer' param as true.

Request attributes

is_update_customer boolean Boolean to update the address for all draft, unpaid invoices and future invoices.

Sample Request

{
          "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District",
          "city": "Beijing",
          "state": "Beijing",
          "zip": "1000881",
          "country": "China",
          "fax": "+86-10-82637827",
          "is_update_customer": false
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Billing address updated"
    }

Update shipping address

PUT  /invoices/:invoice_id/address/shipping

Updates the shipping address for this invoice. You can set this address as default shipping address for your customer by specifying 'is_update_customer' param as true.

Request attributes

is_update_customer boolean Boolean to update the address for all draft, unpaid invoices and future invoices.

Sample Request

{
          "address": "4900 Hopyard Rd, Suit 310",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "945881",
          "country": "USA",
          "fax": "+1-925-924-9600",
          "is_update_customer": false
    }

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Shipping address updated"
    }

List invoice templates

GET  /invoices/templates

Get all invoice pdf templates.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "templates": [
    {
      "template_name": "Service - Classic",
      "template_id": "982000000000107",
      "template_type": "classic"
    }
  ]
}

Update invoice template

PUT  /invoices/:invoice_id/templates/:template_id

Update the pdf template associated with the invoice.

Sample Response


Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Invoice information has been updated."
}