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.

Download Retainer Invoices OpenAPI Document

End Points

POST

/retainerinvoices/{retainerinvoice_id}

GET

/retainerinvoices/{retainerinvoice_id}

DELETE

/retainerinvoices/{retainerinvoice_id}

POST

/retainerinvoices/{retainerinvoice_id}/status/sent

PUT

/retainerinvoices/{retainerinvoice_id}/templates/{template_id}

POST

/retainerinvoices/{retainerinvoice_id}/status/void

POST

/retainerinvoices/{reatinerinvoice_id}/status/draft

POST

/retainerinvoices/{reatinerinvoice_id}/submit

POST

/retainerinvoices/{reatinerinvoice_id}/approve

POST

/retainerinvoices/{retainerinvoice_id}/email

GET

/retainerinvoices/{retainerinvoice_id}/email

PUT

/retainerinvoices/{retainerinvoice_id}/address/billing

GET

/retainerinvoices/templates

POST

/retainerinvoices/{retainerinvoice_id}/attachment

GET

/retainerinvoices/{retainerinvoice_id}/attachment

DELETE

/retainerinvoices/{retainerinvoice_id}/documents/{document_id}

POST

/retainerinvoices/{retainerinvoice_id}/comments

GET

/retainerinvoices/{retainerinvoice_id}/comments

PUT

/retainerinvoices/{retainerinvoice_id}/comments/{comment_id}

DELETE

/retainerinvoices/{retainerinvoice_id}/comments/{comment_id}

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

🇮🇳 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_associated

array

Contact Persons associated with the transaction.

Show Sub-Attributes

contact_person_id

long

Unique ID of the Contact Person.

contact_person_name

string

Name of the Contact Person

first_name

string

First Name of the Contact Person.

last_name

string

Last Name of the Contact Person.

contact_person_email

string

Email ID of the Contact Person.

phone

string

Phone Number of the Contact Person.

mobile

string

Mobile Number of the Contact Person.

communication_preference

object

Preferred modes of communication for the contact person at transaction level.

Show Sub-Attributes

is_email_enabled

boolean

Used to check if Email communication preference is enabled for the contact person at transaction level.

is_whatsapp_enabled

boolean

WhatsApp integration only

Used to check if WhatsApp communication preference is enabled for the contact person at transaction level.

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

location_id

string

Location ID

location_name

string

Name of the location.

line_items

array

Line items of a retainer invoice.

Show Sub-Attributes

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

location_id

string

Location ID

location_name

string

Name of the location.

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

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

payment_gateways

array

Online payment gateways through which payment can be made.

Show Sub-Attributes

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

address

string

street2

string

city

string

state

string

zip

string

country

string

fax

string

shipping_address

object

Show Sub-Attributes

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

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

{
    "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_associated": [
        {
            "contact_person_id": 982000000567003,
            "contact_person_name": "David",
            "first_name": "David",
            "last_name": "Sujin",
            "contact_person_email": "willsmith@bowmanfurniture.com",
            "phone": "+1-925-921-9201",
            "mobile": "+1-4054439562",
            "communication_preference": {
                "is_email_enabled": true,
                "is_whatsapp_enabled": true
            }
        }
    ],
    "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,
    "location_id": "460000000038080",
    "location_name": "string",
    "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,
            "location_id": "460000000038080",
            "location_name": "string"
        }
    ],
    "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.
OAuth Scope : 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_associated

array

Contact Persons associated with the transaction.

Show Sub-Attributes

contact_person_id

long

Unique ID of the Contact Person.

communication_preference

object

Preferred modes of communication for the contact person at transaction level.

Show Sub-Attributes

is_email_enabled

boolean

Used to check if Email communication preference is enabled for the contact person at transaction level.

is_whatsapp_enabled

boolean

WhatsApp integration only

Used to check if WhatsApp communication preference is enabled for the contact person at transaction level.

custom_fields

array

Custom fields for a reatiner invoice.

Show Sub-Attributes

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.

location_id

string

Location ID

line_items

array

(Required)

Line items of an invoice.

Show Sub-Attributes

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

payment_gateways

array

Online payment gateways through which payment can be made.

Show Sub-Attributes

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

🇮🇳 only

Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)

Query Parameters

organization_id

string

(Required)

ID of the organization

ignore_auto_number_generation

boolean

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

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/books/v3/retainerinvoices?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "customer_id": 982000000567001,
    "reference_number": " ",
    "date": "2013-11-17",
    "contact_persons_associated": [
        {
            "contact_person_id": 982000000567003,
            "communication_preference": {
                "is_email_enabled": true,
                "is_whatsapp_enabled": true
            }
        }
    ],
    "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",
    "location_id": "460000000038080",
    "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"
}

{
    "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_associated": [
            {
                "contact_person_id": 982000000567003,
                "contact_person_name": "David",
                "first_name": "David",
                "last_name": "Sujin",
                "contact_person_email": "willsmith@bowmanfurniture.com",
                "phone": "+1-925-921-9201",
                "mobile": "+1-4054439562",
                "communication_preference": {
                    "is_email_enabled": true,
                    "is_whatsapp_enabled": true
                }
            }
        ],
        "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,
        "location_id": "460000000038080",
        "location_name": "string",
        "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,
                "location_id": "460000000038080",
                "location_name": "string"
            }
        ],
        "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.
OAuth Scope : ZohoBooks.invoices.READ

Query Parameters

organization_id

string

(Required)

ID of the organization

boolean

Print the exported pdf.

sort_column

string

Sort retainer invoices.Allowed Values: customer_name, retainer invoice_number, date, due_date, total, balance and created_time

filter_by

string

Filter invoices by any status or payment expected date.Allowed Values: Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate

sort_order

string

The order for sorting

page

integer

Number of pages

per_page

integer

Number of records to be fetched per page. Default value is 200.

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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.
OAuth Scope : 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_associated

array

Contact Persons associated with the transaction.

Show Sub-Attributes

contact_person_id

long

Unique ID of the Contact Person.

communication_preference

object

Preferred modes of communication for the contact person at transaction level.

Show Sub-Attributes

is_email_enabled

boolean

Used to check if Email communication preference is enabled for the contact person at transaction level.

is_whatsapp_enabled

boolean

WhatsApp integration only

Used to check if WhatsApp communication preference is enabled for the contact person at transaction level.

custom_fields

array

Custom fields for a reatiner invoice.

Show Sub-Attributes

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.

location_id

string

Location ID

line_items

array

(Required)

Line items of a retainer invoice.

Show Sub-Attributes

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

payment_gateways

array

Online payment gateways through which payment can be made.

Show Sub-Attributes

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

🇮🇳 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

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/books/v3/retainerinvoices/982000000567114?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request PUT \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "customer_id": 982000000567001,
    "reference_number": " ",
    "date": "2013-11-17",
    "contact_persons_associated": [
        {
            "contact_person_id": 982000000567003,
            "communication_preference": {
                "is_email_enabled": true,
                "is_whatsapp_enabled": true
            }
        }
    ],
    "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",
    "location_id": "460000000038080",
    "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
}

{
    "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_associated": [
            {
                "contact_person_id": 982000000567003,
                "contact_person_name": "David",
                "first_name": "David",
                "last_name": "Sujin",
                "contact_person_email": "willsmith@bowmanfurniture.com",
                "phone": "+1-925-921-9201",
                "mobile": "+1-4054439562",
                "communication_preference": {
                    "is_email_enabled": true,
                    "is_whatsapp_enabled": true
                }
            }
        ],
        "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,
        "location_id": "460000000038080",
        "location_name": "string",
        "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,
                "location_id": "460000000038080",
                "location_name": "string"
            }
        ],
        "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.
OAuth Scope : ZohoBooks.invoices.READ

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices/982000000567114?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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_associated": [
            {
                "contact_person_id": 982000000567003,
                "contact_person_name": "David",
                "first_name": "David",
                "last_name": "Sujin",
                "contact_person_email": "willsmith@bowmanfurniture.com",
                "phone": "+1-925-921-9201",
                "mobile": "+1-4054439562",
                "communication_preference": {
                    "is_email_enabled": true,
                    "is_whatsapp_enabled": true
                }
            }
        ],
        "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,
        "location_id": "460000000038080",
        "location_name": "string",
        "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,
                "location_id": "460000000038080",
                "location_name": "string"
            }
        ],
        "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.
OAuth Scope : ZohoBooks.invoices.DELETE

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695")
  .delete(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("DELETE", "/books/v3/retainerinvoices/982000000567114?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request DELETE \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Mark a retainer invoice as sent

Mark a draft retainer invoice as sent.
OAuth Scope : ZohoBooks.invoices.CREATE

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695")
  .post(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/sent?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Update retainer invoice template

Update the pdf template associated with the retainer invoice.
OAuth Scope : ZohoBooks.invoices.UPDATE

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

template_id

string

(Required)

Unique identifier of the retainer invoice template.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695"
type: PUT
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695")
  .put(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("PUT", "/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request PUT \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/templates/982000000000143?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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.
OAuth Scope : ZohoBooks.invoices.CREATE

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695")
  .post(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/void?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Mark as draft

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

Path Parameters

reatinerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695")
  .post(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/status/draft?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Submit a retainer invoice for approval

Submit a retainer invoice for approval.
OAuth Scope : ZohoBooks.invoices.CREATE

Path Parameters

reatinerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695")
  .post(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/submit?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Approve a retainer invoice.

Approve a retainer invoice.
OAuth Scope : ZohoBooks.invoices.CREATE

Path Parameters

reatinerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695")
  .post(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/approve?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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.
OAuth Scope : 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

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

send_customer_statement

boolean

Send customer statement pdf a with email.

send_attachment

boolean

Send the retainer invoice attachment a with the email.

attachments

binary

Files to be attached to the email

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "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\","
}

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

Get retainer invoice email content

Get the email content of a retainer invoice.
OAuth Scope : ZohoBooks.invoices.READ

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/email?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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": "David",
            "selected": false,
            "phone": "+1-925-921-9201",
            "email": "willsmith@bowmanfurniture.com",
            "last_name": "Sujin",
            "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.
OAuth Scope : 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

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request PUT \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/address/billing?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "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.
OAuth Scope : ZohoBooks.invoices.READ

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/templates?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/templates?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/templates?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices/templates?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/templates?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/templates?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Add attachment to a retainer invoice

Attach a file to an invoice.
OAuth Scope : ZohoBooks.invoices.CREATE

Arguments

can_send_in_mail

boolean

attachment

binary

The file to be attached. It has to be sent in multipart/formdata

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "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.
OAuth Scope : ZohoBooks.invoices.READ

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/attachment?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Delete an attachment

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

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

document_id

string

(Required)

Unique identifier of the retainer invoice document.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695")
  .delete(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("DELETE", "/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request DELETE \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/documents/982000000567115?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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

Add comment

Add a comment for a retainer invoice.
OAuth Scope : ZohoBooks.invoices.CREATE

Arguments

description

string

The description of the comment. Max-length [2000]

payment_expected_date

string

show_comment_to_clients

boolean

Boolean to check if the comment to be shown to the clients

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "description": "comment added",
    "payment_expected_date": " ",
    "show_comment_to_clients": true
}

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

List retainer invoice comments & history

Get the complete history and comments of a retainer invoice.
OAuth Scope : ZohoBooks.invoices.READ

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "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"
        },
        {...},
        {...}
    ]
}

Update comment

Update an existing comment of a retainer invoice.
OAuth Scope : 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

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

comment_id

string

(Required)

Unique identifier of the comment.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request PUT \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "description": "string",
    "show_comment_to_clients": true
}

{
    "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.
OAuth Scope : ZohoBooks.invoices.DELETE

Path Parameters

retainerinvoice_id

string

(Required)

Unique identifier of the retainer invoice.

comment_id

string

(Required)

Unique identifier of the comment.

Query Parameters

organization_id

string

(Required)

ID of the organization

Request Example

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695")
  .delete(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("DELETE", "/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request DELETE \
  --url 'https://www.zohoapis.com/books/v3/retainerinvoices/982000000567114/comments/982000000567019?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

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