API Docs
/
No Results Found
FAQ
Help Docs
All Resources
Retainer Invoices

Retainer Invoices

A retainer invoice is an advanced payment from a customer before we record any transaction with him.

Possible error codes:
Error CodeMessage
9520Retainer Invoices for which payments have been recorded cannot be deleted
9533Cannot modify Retainer Invoice amount, once the payment is recorded

End Points
Create a retainer invoice
List Retainer invoices
Update a retainer invoice
Get a retainer invoice
Delete a retainer invoice
Mark a retainer invoice as sent
Update retainer invoice template
Void a retainer invoice
Mark as draft
Email a retainer invoice
Get retainer invoice email content
Update billing address
List retainer invoice templates
List retainer payments
Delete a retainer payment
Add attachment to a retainer invoice
Get a retainer invoice attachment
Delete an attachment
List retainer invoice comments & history
Add comment
Update comment
Delete a comment

Attribute

retainerinvoice_id
string
The id of the retainerinvoice
retainerinvoice_number
string
number of the retainer invoice.
date
string
The date of creation of the retainer invoice.
status
string
retainer invoice status.Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
is_pre_gst
string
Applicable for transactions that fall before july 1, 2017
place_of_supply
string
🇮🇳 India
only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
project_id
string
ID of the project
project_name
string
Name of the project
last_payment_date
string
The last payment date of the retainer invoice
reference_number
string
The reference number of the retainer invoice. Maximum length [100]
customer_id
string
ID of the customer the retainer invoice has to be created.
customer_name
string
The name of the customer. Maximum length [100]
contact_persons
array
The conatct persons associated with the contact.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the retainer invoice is created.
currency_symbol
string
The currency symbol in which the retainer invoice is created.
exchange_rate
float
Exchange rate of the currency.
is_viewed_by_client
boolean
Boolean is retainer invoice viewed by client in client portal.
client_viewed_time
boolean
client viewed time for retainer invoice in client portal.
is_inclusive_tax
boolean
To check if the total amount is inclusive of tax
line_items
array
Line items of a retainer invoice.
Show Sub-Attributes arrow
line_item_id
string
The line item ID
description
string
The description of the line items. Maximum length [2000]
item_order
integer
The order of the line item_order
rate
double
Rate of the line item.
bcy_rate
double
base currency rate
tax_id
string
ID of the tax or tax group applied to the estimate
tax_name
string
The name of the tax
tax_type
string
The type of the tax
tax_percentage
float
The percentage of tax levied
item_total
float
The total amount of the line items
sub_total
float
The sub total of the all items
total
string
The total amount to be paid
taxes
array
List of the taxes levied
Show Sub-Attributes arrow
tax_name
string
The name of the tax
tax_amount
float
The amount of the tax levied
payment_made
float
The amount paid
payment_drawn
float
The amount drawn
balance
string
The unpaid amount
allow_partial_payments
boolean
Boolean to check if partial payments are allowed for the contact
price_precision
integer
The precision value on the price
payment_options
object
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
Show Sub-Attributes arrow
payment_gateways
array
Online payment gateways through which payment can be made.
Show Sub-Attributes arrow
gateway_name
string
Name of the payment gateway associated with the retainer invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
is_emailed
string
Boolean check to if the email was sent
documents
array
documents attached to the retainer invoice
billing_address
object
Organisation's billing address
Show Sub-Attributes arrow
address
string
Organisation's Billing address
street2
string
city
string
City of Organisation's billing address
state
string
State where organisation's billing location is mentioned
zip
string
ZIP of organisation's billing address
country
string
Country of organisation's billing address
fax
string
FAX number of organisation's billing address
shipping_address
object
Organisation's shipping address
Show Sub-Attributes arrow
address
string
Organisation's Billing address
street2
string
city
string
City of Organisation's billing address
state
string
State where organisation's billing location is mentioned
zip
string
ZIP of organisation's billing address
country
string
Country of organisation's billing address
fax
string
FAX number of organisation's billing address
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
The terms added below expressing gratitude or for conveying some information.
custom_fields
array
Custom fields for a retainer invoice.
Show Sub-Attributes arrow
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
The index of the custom field
label
string
Name of the custom field
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
integer
Value of the custom field
template_id
string
ID of the pdf template associated with the retainer invoice.
template_name
string
Name of template used by organisation
page_width
string
Width of page of contents
page_height
string
Height of page of contents
orientation
string
Page orientation
template_type
string
The type of template type
created_time
string
The time of creation of the retainer invoice
last_modified_time
string
The time of last modification of the retainer invoice
created_by_id
string
Filted by ID of comment
attachment_name
string
name of file attached
can_send_in_mail
boolean
Check if attachment can be sent via mail
invoice_url
string
Url link of invoice

Example

{ "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "project_name": "string", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" }

Create a retainer invoice

Create a retainer invoice for your customer.
oauthscope : ZohoInvoice.invoices.CREATE

Arguments

customer_id
string
(Required)
ID of the customer the retainer invoice has to be created.
reference_number
string
The reference number of the retainer invoice. Maximum length [100]
date
string
The date of creation of the retainer invoice.
contact_persons
array
The conatct persons associated with the contact.
custom_fields
array
Custom fields for a retainer invoice.
Show Sub-Attributes arrow
label
string
Name of the custom field
value
integer
Value of the custom field
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
The terms added below expressing gratitude or for conveying some information.
line_items
array
(Required)
Line items of an invoice.
Show Sub-Attributes arrow
description
string
The description of the line items. Maximum length [2000]
item_order
integer
The order of the line item_order
rate
double
Rate of the line item.
payment_options
object
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
Show Sub-Attributes arrow
payment_gateways
array
Online payment gateways through which payment can be made.
Show Sub-Attributes arrow
gateway_name
string
Name of the payment gateway associated with the retainer invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
template_id
string
ID of the pdf template associated with the retainer invoice.
place_of_supply
string
🇮🇳 India
only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)

Query Parameters

ignore_auto_number_generation
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values true and false

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "label": "Record Number", "value": 23 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }

Response Example

{ "code": 0, "message": "The retainer invoice has been created.", "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "project_name": "string", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

List Retainer invoices

List all retainer invoices with pagination.
oauthscope : ZohoInvoice.invoices.READ

Query Parameters

print
Print the exported pdf.
sort_column
Sort retainer invoices.Allowed Values: customer_name, retainer invoice_number, date, due_date, total, balance and created_time
filter_by
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
sort_order
The order for sorting
page
Number of pages

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "retainerinvoices": [ { "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }, {...}, {...} ] }

Update a retainer invoice

Update an existing invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

Arguments

customer_id
string
(Required)
ID of the customer the retainer invoice has to be created.
reference_number
string
The reference number of the retainer invoice. Maximum length [100]
date
string
The date of creation of the retainer invoice.
contact_persons
array
The conatct persons associated with the contact.
custom_fields
array
Custom fields for a retainer invoice.
Show Sub-Attributes arrow
label
string
Name of the custom field
value
integer
Value of the custom field
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
The terms added below expressing gratitude or for conveying some information.
line_items
array
(Required)
Line items of a retainer invoice.
Show Sub-Attributes arrow
description
string
The description of the line items. Maximum length [2000]
item_order
integer
The order of the line item_order
rate
double
Rate of the line item.
payment_options
object
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
Show Sub-Attributes arrow
payment_gateways
array
Online payment gateways through which payment can be made.
Show Sub-Attributes arrow
gateway_name
string
Name of the payment gateway associated with the retainer invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
template_id
string
ID of the pdf template associated with the retainer invoice.
place_of_supply
string
🇮🇳 India
only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
project_id
string
ID of the project

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "label": "Record Number", "value": 23 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN", "project_id": 982000000567154 }

Response Example

{ "code": 0, "message": "Retainer Invoice information has been updated.", "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "project_name": "string", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Get a retainer invoice

Get the details of a retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "project_name": "string", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 }, "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Delete a retainer invoice

Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted.
oauthscope : ZohoInvoice.invoices.DELETE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The retainer invoice has been deleted." }

Mark a retainer invoice as sent

Mark a draft retainer invoice as sent.
oauthscope : ZohoInvoice.invoices.CREATE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/sent -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Retainer Invoice status has been changed to Sent." }

Update retainer invoice template

Update the pdf template associated with the retainer invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Retainer Invoice information has been updated." }

Void a retainer invoice

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

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/void -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Retainer Invoice status has been changed to 'Void'." }

Mark as draft

Mark a voided retainer invoice as draft.
oauthscope : ZohoInvoice.invoices.CREATE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/status/draft -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Status of retainer invoice changed from void to draft." }

Email a retainer invoice

Email a retainer invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
oauthscope : ZohoInvoice.invoices.CREATE

Arguments

send_from_org_email_id
boolean
Boolean to trigger the email from the organization's email address
to_mail_ids
array
(Required)
Array of email address of the recipients.
cc_mail_ids
array
Array of email address of the recipients to be CC'd.
subject
string
The subject of the mail
body
string
The body of the mail

Query Parameters

send_customer_statement
Send customer statement pdf a with email.
send_attachment
Send the retainer invoice attachment a with the email.
attachments
Files to be attached to the email

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "send_from_org_email_id": false, "to_mail_ids": [ "test@zylker.org" ], "cc_mail_ids": [ "test@zylker.org" ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/portal/zylkar/secure?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\"," }

Response Example

{ "code": 0, "message": "Your retainer invoice has been sent." }

Get retainer invoice email content

Get the email content of a retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "gateways_configured": true, "deprecated_placeholders_used": [], "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/portal/zylkar/secure?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\",", "error_list": [], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "to_contacts": [ { "first_name": "Will", "selected": false, "phone": "1234", "email": "test@zylker.org", "last_name": "Smith", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "1234" } ], "attachment_name": "new file", "email_template_id": "string", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": false, "email": "test@zylker.org" } ], "customer_id": 982000000567001 }

Update billing address

Updates the billing address for this retainer invoice alone.
oauthscope : ZohoInvoice.invoices.UPDATE

Arguments

address
string
address of the customer
city
string
city of the customer
state
string
state of the customer
zip
string
zip of the customer
country
string
country of the customer
fax
string
fax of the customer

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/address/billing -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

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

Response Example

{ "code": 0, "message": "Billing address updated" }

List retainer invoice templates

Get all retainer invoice pdf templates.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/templates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" }, {...}, {...} ] }

List retainer payments

Get the list of payments made for a retainer invoices.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainerinvoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "payments": [ { "payment_id": "982000000567190", "documents": [], "customer_id": 982000000567001, "customer_name": "Bowman & Co", "retainerinvoice_id": 982000000567114, "payment_mode": "cash", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "amount": 100, "unused_amount": 100, "bank_charges": 20, "is_client_review_settings_enabled": true, "tax_amount_withheld": 10, "discount_amount": 10, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "reference_number": " ", "online_transaction_id": "7843653940324085", "invoices": [], "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "retainerinvoice_total": 3478, "retainerinvoice_balance": 3478, "retainerinvoice_date": "2016-12-20" }, "payment_refunds": [], "last_four_digits": "", "html_string": "", "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "attachment_name": "new file", "can_send_in_mail": true, "is_payment_drawn_details_required": true, "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] }, {...}, {...} ] }

Delete a retainer payment

Delete a payment made to a retainer invoice.
oauthscope : ZohoInvoice.invoices.DELETE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainer_payment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The payment has been deleted." }

Add attachment to a retainer invoice

Attach a file to an invoice.
oauthscope : ZohoInvoice.invoices.CREATE

Arguments

can_send_in_mail
boolean
Check if attachment can be sent via mail
attachment
binary
The file to be attached. It has to be sent in multipart/formdata

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "can_send_in_mail": true, "attachment": "string" }

Response Example

{ "code": 0, "message": "Your file has been attached." }

Get a retainer invoice attachment

Returns the file attached to the retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success" }

Delete an attachment

Delete the file attached to the retainer invoice.
oauthscope : ZohoInvoice.invoices.DELETE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/documents/{document_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Your file is no longer attached to the invoice." }

List retainer invoice comments & history

Get the complete history and comments of a retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainernvoice_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "transaction_id": "982000000567204", "transaction_type": "retainer_payment" }, {...}, {...} ] }

Add comment

Add a comment for a retainer invoice.
oauthscope : ZohoInvoice.invoices.CREATE

Arguments

description
string
The description of the line items. Maximum length [2000]
payment_expected_date
string
Actual date when payment is expected to be cedited
show_comment_to_clients
boolean
Boolean to check if the comment to be shown to the clients

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "description": "comment added", "payment_expected_date": " ", "show_comment_to_clients": true }

Response Example

{ "code": 0, "message": "Comments added." }

Update comment

Update an existing comment of a retainer invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

Arguments

description
string
The description of the line items. Maximum length [2000]
show_comment_to_clients
boolean
Boolean to check if the comment to be shown to the clients

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "description": "comment updated", "show_comment_to_clients": true }

Response Example

{ "code": 0, "message": "The comment has been deleted.", "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "comment_type": "system" }

Delete a comment

Delete a retainer invoice comment.
oauthscope : ZohoInvoice.invoices.DELETE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The comment has been deleted." }