Zoho Inventory retainer-invoices API
Retainer-Invoices Module
OpenAPI Specification
openapi: 3.0.0
info:
title: batches retainer-invoices API
description: Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.
contact: {}
version: 1.0.0
servers:
- url: https://www.zohoapis.com/inventory/v1
description: API Endpoint
tags:
- name: retainer-invoices
description: Retainer-Invoices Module
paths:
/retainerinvoices:
x-mcp-group:
- Retainer Invoices
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: create_retainer_invoice
summary: Create a retainerinvoice
description: Create a retainer invoice for your customer.
parameters:
- name: ignore_auto_number_generation
in: query
description: Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values <code>true</code> and <code>false</code>
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-retainerinvoice-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-retainerinvoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
get:
tags:
- retainer-invoices
operationId: list_retainer_invoices
summary: List a retainer invoices
description: List all retainer invoices with pagination.
parameters:
- name: print
in: query
description: Print the exported pdf.
required: false
schema:
type: boolean
- name: sort_column
in: query
description: 'Sort retainer invoices.Allowed Values: <code>customer_name</code>, <code>retainer invoice_number</code>, <code>date</code>, <code> due_date</code>, <code>total</code>, <code>balance</code> and <code>created_time</code>'
required: false
schema:
type: string
example: created_time
- name: filter_by
in: query
description: 'Filter invoices by any status or payment expected date.Allowed Values: <code> Status.All</code>, <code>Status.Sent</code>, <code> Status.Draft</code>, <code>Status.OverDue</code>, <code>Status.Paid</code>, <code>Status.Void</code>, <code>Status.Unpaid</code>, <code>Status.PartiallyPaid</code>,<code> Status.Viewed</code> and <code>Date.PaymentExpectedDate</code>'
required: false
schema:
type: string
example: ''
- name: sort_order
in: query
description: The order for sorting
required: false
schema:
type: string
example: D
- name: page
in: query
description: Number of pages
required: false
schema:
type: integer
example: 1
- name: per_page
in: query
description: Number of records to be fetched per page. Default value is 200.
required: false
schema:
type: integer
default: 200
example: 200
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-a-retainer-invoices-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
/retainerinvoices/{retainerinvoice_id}:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
put:
tags:
- retainer-invoices
operationId: update_retainer_invoice
summary: update a retainerinvoice
description: Update an existing invoice.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-retainerinvoice-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-retainerinvoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.UPDATE
get:
tags:
- retainer-invoices
operationId: get_retainer_invoice
summary: Get a retainer invoice
description: Get the details of a retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
delete:
tags:
- retainer-invoices
operationId: delete_retainer_invoice
summary: Delete a retainer invoice
description: Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.DELETE
/retainerinvoices/{retainerinvoice_id}/status/sent:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: mark_retainer_invoice_as_sent
summary: Mark a retainer invoice as sent
description: Mark a draft retainer invoice as sent.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-a-retainer-invoice-as-sent-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{retainerinvoice_id}/templates/{template_id}:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- name: template_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice template.
example: 982000000000143
- $ref: '#/components/parameters/organization_id'
put:
tags:
- retainer-invoices
operationId: update_retainer_invoice_template
summary: Update retainer invoice template
description: Update the pdf template associated with the retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-retainer-invoice-template-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.UPDATE
/retainerinvoices/{retainerinvoice_id}/status/void:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: mark_retainer_invoice_as_void
summary: Void a retainer invoice
description: 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.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/void-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{reatinerinvoice_id}/status/draft:
x-mcp-group:
- Retainer Invoices
parameters:
- name: reatinerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: '982000000567114'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: mark_retainer_invoice_as_draft
summary: Mark as draft
description: 'Mark a voided retainer invoice as draft. '
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-draft-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{reatinerinvoice_id}/submit:
x-mcp-group:
- Retainer Invoices
parameters:
- name: reatinerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: '982000000567114'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: submit_retainer_invoice
summary: Submit a retainer invoice for approval
description: Submit a retainer invoice for approval.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/submit-a-retainer-invoice-for-approval-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{reatinerinvoice_id}/approve:
x-mcp-group:
- Retainer Invoices
parameters:
- name: reatinerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: '982000000567114'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: approve_retainer_invoice
summary: Approve a retainer invoice.
description: Approve a retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approve-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{retainerinvoice_id}/email:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
post:
tags:
- retainer-invoices
operationId: email_retainer_invoice
summary: Email a retainer invoice
description: 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.
parameters:
- name: send_customer_statement
in: query
description: Send customer statement pdf a with email.
required: false
schema:
type: boolean
example: ' '
- name: send_attachment
in: query
description: Send the retainer invoice attachment a with the email.
required: false
schema:
type: boolean
example: ' '
- name: attachments
in: query
description: Files to be attached to the email
required: false
schema:
type: string
format: binary
example: ''
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/email-a-retainer-invoice-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/email-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
get:
tags:
- retainer-invoices
operationId: get_retainer_invoice_email_content
summary: Get retainer invoice email content
description: Get the email content of a retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-retainer-invoice-email-content-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
/retainerinvoices/{retainerinvoice_id}/address/billing:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
put:
tags:
- retainer-invoices
operationId: update_retainer_invoice_billing_address
summary: Update billing address
description: Updates the billing address for this retainer invoice alone.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-billing-address-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-billing-address-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.UPDATE
/retainerinvoices/templates:
x-mcp-group:
- Retainer Invoices
parameters:
- $ref: '#/components/parameters/organization_id'
get:
tags:
- retainer-invoices
operationId: list_retainer_invoice_templates
summary: List retainer invoice templates
description: Get all retainer invoice pdf templates.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-retainer-invoice-templates-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
/retainerinvoices/{retainerinvoice_id}/attachment:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
get:
tags:
- retainer-invoices
operationId: get_retainer_invoice_attachment
summary: Get a retainer invoice attachment
description: Returns the file attached to the retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-a-retainer-invoice-attachment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
post:
tags:
- retainer-invoices
operationId: add_attachment_to_retainer_invoice
summary: Add attachment to a retainer invoice
description: Attach a file to an invoice.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/add-attachment-to-a-retainer-invoice-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/add-attachment-to-a-retainer-invoice-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{retainerinvoice_id}/documents/{document_id}:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- name: document_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice document.
example: '982000000562114'
- $ref: '#/components/parameters/organization_id'
delete:
tags:
- retainer-invoices
operationId: delete_retainer_invoice_attachment
summary: Delete an attachment
description: Delete the file attached to the retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-an-attachment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.DELETE
/retainerinvoices/{retainerinvoice_id}/comments:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- $ref: '#/components/parameters/organization_id'
get:
tags:
- retainer-invoices
operationId: list_retainer_invoice_comments
summary: List retainer invoice comments & history
description: Get the complete history and comments of a retainer invoice.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-retainer-invoice-comments-and-history-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.READ
post:
tags:
- retainer-invoices
operationId: create_retainer_invoice_comment
summary: Add comment
description: Add a comment for a retainer invoice.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/add-comment-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/add-comment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.CREATE
/retainerinvoices/{retainerinvoice_id}/comments/{comment_id}:
x-mcp-group:
- Retainer Invoices
parameters:
- name: retainerinvoice_id
in: path
schema:
type: string
required: true
description: Unique identifier of the retainer invoice.
example: 982000000567114
- name: comment_id
in: path
schema:
type: string
required: true
description: Unique identifier of the comment.
example: 982000000567019
- $ref: '#/components/parameters/organization_id'
delete:
tags:
- retainer-invoices
operationId: delete_retainer_invoice_comment
summary: Delete a comment
description: Delete a retainer invoice comment.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-comment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.DELETE
put:
tags:
- retainer-invoices
operationId: update_retainer_invoice_comment
summary: Update comment
description: Update an existing comment of a retainer invoice.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-comment-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-comment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.invoices.UPDATE
components:
schemas:
transaction_id:
type: string
example: '982000000567204'
payment_expected_date:
type: string
description: The date on which the payment is expected to be received for the retainer invoice.
example: ' '
update-comment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The comment has been updated.
readOnly: true
comment:
type: object
properties:
comment_id:
$ref: '#/components/schemas/comment_id'
retainerinvoice_id:
$ref: '#/components/schemas/retainerinvoice_id'
description:
$ref: '#/components/schemas/description'
commented_by_id:
$ref: '#/components/schemas/commented_by_id'
commented_by:
$ref: '#/components/schemas/commented_by'
date:
$ref: '#/components/schemas/date'
date_description:
$ref: '#/components/schemas/date_description'
time:
$ref: '#/components/schemas/time'
comment_type:
$ref: '#/components/schemas/comment_type'
terms:
description: The terms added below expressing gratitude or for conveying some information.
type: string
example: Terms & Conditions apply
contact_persons_associated:
description: Contact Persons associated with the retainer invoice.
type: array
items:
type: object
properties:
contact_person_id:
$ref: '#/components/schemas/contact_person_id'
contact_person_name:
$ref: '#/components/schemas/contact_person_name'
first_name:
$ref: '#/components/schemas/first_name'
last_name:
$ref: '#/components/schemas/last_name'
contact_person_email:
$ref: '#/components/schemas/contact_person_email'
phone:
$ref: '#/components/schemas/phone'
mobile:
$ref: '#/components/schemas/mobile'
communication_preference:
$ref: '#/components/schemas/communication_preference'
taxes:
description: List of the taxes levied
type: array
items:
type: object
properties:
tax_name:
$ref: '#/components/schemas/tax_name'
tax_amount:
$ref: '#/components/schemas/tax_amount'
mark-as-draft-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Status of retainer invoice changed from void to draft.
readOnly: true
zip:
type: string
example: 94134
user_name:
type: array
items:
type: string
example: John Smith
page:
description: Number of pages
type: integer
example: 1
sub_total:
description: The sub total of the all items
type: number
format: float
example: 153
applied_filter:
description: The filer applied for sorting
type: string
example: Status.All
void-a-retainer-invoice-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Retainer Invoice status has been changed to 'Void'.
readOnly: true
documents:
description: documents attached to the retainer invoice
type: array
items:
type: string
example: []
date:
description: The date of creation of the retainer invoice.
type: string
example: '2013-11-17'
additional_field1:
description: 'Paypal payment method. Allowed Values: <code>standard</code> and <code>adaptive</code>'
type: string
example: standard
item_total:
description: The total amount of the line items
type: number
format: float
example: 120
per_page:
description: Per page values
type: integer
example: 200
custom_fields:
description: Custom fields for a retainer invoice.
type: array
items:
type: object
properties:
customfield_id:
$ref: '#/components/schemas/customfield_id'
show_on_pdf:
$ref: '#/components/schemas/show_on_pdf'
value:
$ref: '#/components/schemas/value'
label:
$ref: '#/components/schemas/label'
approve-a-retainer-invoice-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: You have approved the Retainer Invoice.
readOnly: true
value:
type: string
description: The value of the custom field
example: value1
to_mail_ids:
description: Array of email address of the recipients.
type: array
items:
type: string
example:
- willsmith@bowmanfurniture.com
currency_symbol:
description: The currency symbol in which the retainer invoice is created.
type: string
example: USD
create-a-retainerinvoice-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The retainer invoice has been created.
readOnly: true
retainerinvoice:
$ref: '#/components/schemas/retainerinvoice-response'
contact_person_email:
description: Email ID of the Contact Person.
type: string
example: willsmith@bowmanfurniture.com
show_on_pdf:
description: Boolean value to check if the custom field is to be dispplayed on the pdf.
type: boolean
example: false
create-a-retainerinvoice-request:
required:
- customer_id
- line_items
type: object
properties:
customer_id:
$ref: '#/components/schemas/customer_id'
reference_number:
$ref: '#/components/schemas/reference_number'
date:
$ref: '#/components/schemas/date'
contact_persons_associated:
$ref: '#/components/schemas/contact_persons_associated_payload'
custom_fields:
$ref: '#/components/schemas/custom_fields'
notes:
$ref: '#/components/schemas/notes'
terms:
$ref: '#/components/schemas/terms'
location_id:
$ref: '#/components/schemas/location_id'
line_items:
description: Line items of a retainer invoice.
type: array
items:
type: object
properties:
description:
$ref: '#/components/schemas/description'
item_order:
$ref: '#/components/schemas/item_order'
rate:
$ref: '#/components/schemas/rate'
payment_options:
$ref: '#/components/schemas/payment_options'
template_id:
$ref: '#/components/schemas/template_id'
place_of_supply:
$ref: '#/components/schemas/place_of_supply'
body:
description: The body of the mail
type: string
example: 'Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email.<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",'
list-retainer-invoice-comments-and-history-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
comments:
type: array
items:
type: object
properties:
comment_id:
$ref: '#/components/schemas/comment_id'
retainerinvoice_id:
$ref: '#/components/schemas/retainerinvoice_id'
description:
$ref: '#/components/schemas/description'
commented_by_id:
$ref: '#/components/schemas/commented_by_id'
commented_by:
$ref: '#/components/schemas/commented_by'
comment_type:
$ref: '#/components/schemas/comment_type'
operation_type:
$ref: '#/components/schemas/operation_type'
date:
$ref: '#/components/schemas/date'
date_description:
$ref: '#/components/schemas/date_description'
time:
$ref: '#/components/schemas/time'
transaction_id:
$ref: '#/components/schemas/transaction_id'
transaction_type:
$ref: '#/components/schemas/transaction_type'
retainerinvoice_number:
description: 'number of the retainer invoice.Variants: <code>retainerinvoice_number_startswith</code> and <code>retainerinvoice_number_contains</code>. Max-length [100]'
type: string
example: RET-00003
sort_order:
description: The order for sorting
type: string
example: D
update-billing-address-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Billing address updated
readOnly: true
cc_mail_ids:
description: Array of email address of the recipients to be cced.
type: array
items:
type: string
example:
- peterparker@bowmanfurniture.com
country:
type: string
example: U.S.A
created_by_id:
type: string
example: 14909000000072000
status:
description: 'retainer invoice status.Allowed Values: <code>sent</code>, <code>draft</code>, <code>overdue</code>, <code>paid</code>, <code>void</code>, <code>unpaid</code>, <code>partially_paid</code> and <code>viewed</code>'
type: string
example: draft
transaction_type:
type: string
example: retainer_payment
label:
description: The label of the custom field.
type: string
example: Delivery Date
phone:
description: Phone Number of the Contact Person
type: string
example: +1-925-921-9201
client_viewed_time:
description: client viewed time for retainer invoice in client portal.
type: boolean
example: true
get-a-retainer-invoice-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
retainerinvoice:
type: object
properties:
retainerinvoice_id:
$ref: '#/components/schemas/retainerinvoice_id'
retainerinvoice_number:
$ref: '#/components/schemas/retainerinvoice_number'
date:
$ref: '#/components/schemas/date'
stat
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-retainer-invoices-api-openapi.yml