Retainer Invoices
A retainer invoice is an advanced payment from a customer before we record any transaction with him.
Possible error codes:
Error Code | Message |
---|---|
9520 | Retainer Invoices for which payments have been recorded cannot be deleted |
9533 | Cannot modify Retainer Invoice amount, once the payment is recorded |
Attribute
sent
, draft
, overdue
, paid
, void
, unpaid
, partially_paid
and viewed
place of contact
given for the contact will be taken)Maximum length [100]
Maximum length [100]
Maximum length [2000]
paypal
, authorize_net
, payflow_pro
, stripe
, 2checkout
and braintree
{
"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
Maximum length [100]
Maximum length [2000]
paypal
, authorize_net
, payflow_pro
, stripe
, 2checkout
and braintree
place of contact
given for the contact will be taken)Query Parameters
true
and false
$ 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"}'
{
"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"
}
{
"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
customer_name
, retainer invoice_number
, date
, due_date
, total
, balance
and created_time
Status.All
, Status.Sent
, Status.Draft
, Status.OverDue
, Status.Paid
, Status.Void
, Status.Unpaid
, Status.PartiallyPaid
, Status.Viewed
and Date.PaymentExpectedDate
$ curl https://invoice.zoho.com/api/v3/retainerinvoices
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
Maximum length [100]
Maximum length [2000]
paypal
, authorize_net
, payflow_pro
, stripe
, 2checkout
and braintree
place of contact
given for the contact will be taken)$ 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"}'
{
"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
}
{
"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
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
$ 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"
{
"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
$ 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"
{
"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
$ 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"
{
"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
$ 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"
{
"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
$ 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"
{
"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
Query Parameters
$ 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"}'
{
"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\","
}
{
"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
$ 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"
{
"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
$ 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"}'
{
"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"
}
{
"code": 0,
"message": "Billing address updated"
}
List retainer invoice templates
Get all retainer invoice pdf templates. oauthscope : ZohoInvoice.invoices.READ
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/templates
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainerinvoice_id}
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
$ 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"
{
"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
$ 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"}'
{
"can_send_in_mail": true,
"attachment": "string"
}
{
"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
$ 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"
{
"code": 0,
"message": "success"
}
Delete an attachment
Delete the file attached to the retainer invoice. oauthscope : ZohoInvoice.invoices.DELETE
$ 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"
{
"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
$ 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"
{
"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
Maximum length [2000]
$ 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"}'
{
"description": "comment added",
"payment_expected_date": " ",
"show_comment_to_clients": true
}
{
"code": 0,
"message": "Comments added."
}
Update comment
Update an existing comment of a retainer invoice. oauthscope : ZohoInvoice.invoices.UPDATE
Arguments
Maximum length [2000]
$ 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"}'
{
"description": "comment updated",
"show_comment_to_clients": true
}
{
"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
$ 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"
{
"code": 0,
"message": "The comment has been deleted."
}