API Docs
/
No Results Found
Retainer Invoices

Retainer Invoices

A lot of businesses collect an advance payment (or retainer) for products sold or services rendered by them. This amount collected will not be an income but a liability to the company. The revenue is earned only when the product is delivered or the service is completed, if not delivered or completed the advance payment made will be returned to the customer.

End Points
Create a retainerinvoice
List a retainer invoices
update a retainerinvoice
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
Submit a retainer invoice for approval
Approve a retainer invoice.
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
ID of the retainerinvoice
retainerinvoice_number
string
number of the retainer invoice.Variants: retainerinvoice_number_startswith and retainerinvoice_number_contains. Max-length [100]
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. Max-length [100]
customer_id
string
ID of the customer the retainer invoice has to be created.
customer_name
string
The name of the customer. Max-length [100]
contact_persons
array
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
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. Max-length [2000]
item_order
integer
The order of the line item_order
rate
double
Rate of the line item.
bcy_rate
float
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
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
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
Show Sub-Attributes arrow
address
string
street2
string
city
string
state
string
zip
string
country
string
fax
string
shipping_address
object
Show Sub-Attributes arrow
address
string
city
string
state
string
zip
string
country
string
fax
string
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 reatiner invoice.
Show Sub-Attributes arrow
index
integer
The index of the custom field
show_on_pdf
boolean
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
string
label
string
The label of the custom field.
template_id
string
ID of the pdf template associated with the retainer invoice.
template_name
string
page_width
string
page_height
string
orientation
string
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
attachment_name
string
can_send_in_mail
boolean
invoice_url
string

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" ], "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": [ { "configured": true, "additional_field1": "standard", "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", "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": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" }

Create a retainerinvoice

Create a retainer invoice for your customer.
oauthscope : ZohoBooks.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. Max-length [100]
date
string
The date of creation of the retainer invoice.
contact_persons
array
custom_fields
array
Custom fields for a reatiner invoice.
Show Sub-Attributes arrow
index
integer
The index of the custom field
show_on_pdf
boolean
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
string
label
string
The label 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. Max-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
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
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://books.zoho.com/api/v3/retainerinvoices -X POST -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" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "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": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }

Response Example

{ "code": 0, "message": "The retainer invoice has been created.", "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" ], "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": [ { "configured": true, "additional_field1": "standard", "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", "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": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

List a retainer invoices

List all retainer invoices with pagination.
oauthscope : ZohoBooks.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://books.zoho.com/api/v3/retainerinvoices -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-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }, {...}, {...} ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Retainer Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }

update a retainerinvoice

Update an existing invoice.
oauthscope : ZohoBooks.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. Max-length [100]
date
string
The date of creation of the retainer invoice.
contact_persons
array
custom_fields
array
Custom fields for a reatiner invoice.
Show Sub-Attributes arrow
index
integer
The index of the custom field
show_on_pdf
boolean
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
string
label
string
The label 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. Max-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
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
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://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "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": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN", "project_id": 982000000567154 }

Response Example

{ "code": 0, "message": "Retainer Invoice information has been updated.", "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" ], "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": [ { "configured": true, "additional_field1": "standard", "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", "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": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Get a retainer invoice

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}

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" ], "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": [ { "configured": true, "additional_field1": "standard", "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", "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": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Delete a retainer invoice

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X DELETE

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 : ZohoBooks.invoices.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/sent -X POST

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 : ZohoBooks.invoices.UPDATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/templates/{template_id} -X PUT

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 : ZohoBooks.invoices.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/void -X POST

Response Example

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

Mark as draft

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/status/draft -X POST

Response Example

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

Submit a retainer invoice for approval

Submit a retainer invoice for approval.
oauthscope : ZohoBooks.invoices.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/submit -X POST

Response Example

{ "code": 0, "message": "The Retainer Invoice has been successfully submitted for approval." }

Approve a retainer invoice.

Approve a retainer invoice.
oauthscope : ZohoBooks.invoices.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/approve -X POST

Response Example

{ "code": 0, "message": "You have approved the Retainer Invoice." }

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 : ZohoBooks.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 cced.
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://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email -X POST -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": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "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/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\"," }

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 : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email

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/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\",", "error_list": [], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-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" } ], "attachment_name": "new file", "email_template_id": "string", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": false, "email": "willsmith@bowmanfurniture.com" } ], "customer_id": 982000000567001 }

Update billing address

Updates the billing address for this retainer invoice alone.
oauthscope : ZohoBooks.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://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/address/billing -X PUT -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 : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/templates

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 : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{retainerinvoice_id}

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": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ] }, {...}, {...} ] }

Delete a retainer payment

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{retainer_payment_id} -X DELETE

Response Example

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

Add attachment to a retainer invoice

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

Arguments

can_send_in_mail
boolean
attachment
binary
The file to be attached. It has to be sent in multipart/formdata

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment -X POST -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 : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment

Response Example

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

Delete an attachment

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/documents/{document_id} -X DELETE

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 : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainernvoice_id}/comments

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 : ZohoBooks.invoices.CREATE

Arguments

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

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments -X POST -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 : ZohoBooks.invoices.UPDATE

Arguments

description
string
The comment on a retainer invoice
show_comment_to_clients
boolean
Boolean to check if the comment to be shown to the clients

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "description": "string", "show_comment_to_clients": true }

Response Example

{ "code": 0, "message": "The comment has been updated.", "comment": { "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 : ZohoBooks.invoices.DELETE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X DELETE

Response Example

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