OpenAPI Specification
openapi: 3.0.0
info:
title: batches bills 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: bills
description: Bills Module
paths:
/bills:
x-mcp-group:
- Bills
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- bills
operationId: create_bill
summary: Create a Bill
description: Creates a Bill in Zoho Inventory. Description about the extra parameter <code>attachment</code> Allowed extensions are gif, png, jpeg, jpg, bmp and pdf.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-bill-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.CREATE
get:
tags:
- bills
operationId: list_bills
summary: List all Bills.
description: Lists all the Bills in Zoho Inventory.
parameters:
- name: page
in: query
description: Page number to be fetched. Default value is 1.
required: false
schema:
type: integer
default: 1
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-all-bills-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.READ
/bills/{bill_id}:
x-mcp-group:
- Bills
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill.
schema:
type: string
example: 4815000000045067
- $ref: '#/components/parameters/organization_id'
get:
tags:
- bills
operationId: get_bill
summary: Retrieve a Bill
description: Fetches the details of a Bill.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/retrieve-a-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.READ
put:
tags:
- bills
operationId: update_bill
summary: Update a Bill
description: Updates the details of an existing Bill.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-bill-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
delete:
tags:
- bills
operationId: delete_bill
summary: Delete a Bill.
description: Deletes a Bill from Zoho Inventory.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.DELETE
/bill/{bill_id}/customfields:
x-mcp-group:
- Bills
put:
tags:
- bills
operationId: update_custom_field_in_bill
summary: Update custom field in existing bills
description: Update the value of the custom field in existing bills.
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill.
schema:
type: string
example: '460000000098765'
- $ref: '#/components/parameters/organization_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/custom_fields'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-an-bill-customfield-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/{bill_id}/status/open:
x-mcp-group:
- Bills
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill.
schema:
type: string
example: 4815000000045067
- $ref: '#/components/parameters/organization_id'
post:
tags:
- bills
operationId: mark_bill_as_open
summary: Mark as Open
description: Marks a Bill as Open.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-open-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.CREATE
/bills/{bill_id}/status/void:
x-mcp-group:
- Bills
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill.
schema:
type: string
example: 4815000000045067
- $ref: '#/components/parameters/organization_id'
post:
tags:
- bills
operationId: mark_bill_as_void
summary: Mark as Void
description: Marks a Bill as Void.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-void-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.CREATE
/bills/{bill_id}/submit:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: submit_bill
summary: Submit a bill for approval
description: Submit a bill for approval workflow.
parameters:
- name: bill_id
in: path
description: Unique ID of the bill.
required: true
schema:
type: string
example: '4815000000045067'
- $ref: '#/components/parameters/organization_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/{bill_id}/approve:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: approve_bill
summary: Approve a bill
description: Approve a submitted bill.
parameters:
- name: bill_id
in: path
description: Unique ID of the bill.
required: true
schema:
type: string
example: '4815000000045067'
- $ref: '#/components/parameters/organization_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/{bill_id}/approve/final:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: approve_bill_final
summary: Final approval of a bill
description: Perform the final approval of a bill (admin only).
parameters:
- name: bill_id
in: path
description: Unique ID of the bill.
required: true
schema:
type: string
example: '4815000000045067'
- $ref: '#/components/parameters/organization_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/{bill_id}/reject:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: reject_bill
summary: Reject a bill
description: Reject a submitted bill.
parameters:
- name: bill_id
in: path
description: Unique ID of the bill.
required: true
schema:
type: string
example: '4815000000045067'
- $ref: '#/components/parameters/organization_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reject-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/submit:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: bulk_submit_bills
summary: Bulk submit bills for approval
description: Submit multiple bills for approval workflow at once.
parameters:
- $ref: '#/components/parameters/organization_id'
- name: bill_ids
in: query
description: Comma-separated list of bill IDs to submit for approval.
required: true
schema:
type: string
example: 4815000000045067,4815000000045090
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
/bills/approve:
x-mcp-group:
- Bills
post:
tags:
- bills
operationId: bulk_approve_bills
summary: Bulk approve bills
description: Approve multiple submitted bills at once.
parameters:
- $ref: '#/components/parameters/organization_id'
- name: bill_ids
in: query
description: Comma-separated list of bill IDs to approve.
required: true
schema:
type: string
example: 4815000000045067,4815000000045090
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
components:
schemas:
vendor_credit_number:
type: integer
format: int64
example: 67258
item_custom_fields:
type: array
description: List of custom fields associated with the line item
items:
type: object
properties:
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
terms:
description: Terms and conditions.
type: string
example: Term & Conditions
reverse_charge_tax_amount:
description: Enter reverse charge amount
type: number
format: double
example: 100
x-node_available_in:
- in
x-node_unavailable_in: []
taxes:
description: 'Number of taxes applied on the Purchase Order. Each tax contains: <code>tax_name</code> and <code>tax_amount</code>.'
type: array
items:
type: object
properties:
tax_name:
$ref: '#/components/schemas/tax_name'
tax_amount:
$ref: '#/components/schemas/tax_amount'
create-a-bill-request:
required:
- vendor_id
- bill_number
- date
- due_date
- line_items
type: object
properties:
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
vendor_id:
$ref: '#/components/schemas/vendor_id'
bill_number:
$ref: '#/components/schemas/bill_number'
date:
$ref: '#/components/schemas/date'
due_date:
$ref: '#/components/schemas/due_date'
reference_number:
$ref: '#/components/schemas/reference_number'
currency_id:
$ref: '#/components/schemas/currency_id'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
is_item_level_tax_calc:
$ref: '#/components/schemas/is_item_level_tax_calc'
notes:
$ref: '#/components/schemas/notes'
terms:
$ref: '#/components/schemas/terms'
is_inclusive_tax:
$ref: '#/components/schemas/is_inclusive_tax'
custom_fields:
$ref: '#/components/schemas/custom_fields'
line_items:
description: The line items for a Bill.
type: array
items:
type: object
properties:
purchaseorder_item_id:
$ref: '#/components/schemas/purchaseorder_item_id'
receive_item_id:
$ref: '#/components/schemas/receive_item_id'
line_item_id:
$ref: '#/components/schemas/line_item_id'
name:
$ref: '#/components/schemas/name'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
description:
$ref: '#/components/schemas/description'
bcy_rate:
$ref: '#/components/schemas/bcy_rate'
rate:
$ref: '#/components/schemas/rate'
quantity:
$ref: '#/components/schemas/quantity'
tax_id:
$ref: '#/components/schemas/tax_id'
tds_tax_id:
$ref: '#/components/schemas/tds_tax_id'
tax_name:
$ref: '#/components/schemas/tax_name'
tax_type:
$ref: '#/components/schemas/tax_type'
tax_percentage:
$ref: '#/components/schemas/tax_percentage'
item_total:
$ref: '#/components/schemas/item_total'
item_order:
$ref: '#/components/schemas/item_order'
unit:
$ref: '#/components/schemas/unit'
image_id:
$ref: '#/components/schemas/image_id'
image_name:
$ref: '#/components/schemas/image_name'
image_type:
$ref: '#/components/schemas/image_type'
reverse_charge_tax_id:
$ref: '#/components/schemas/reverse_charge_tax_id'
hsn_or_sac:
$ref: '#/components/schemas/hsn_or_sac'
tax_exemption_code:
$ref: '#/components/schemas/tax_exemption_code'
location_id:
$ref: '#/components/schemas/location_id'
tax_exemption_id:
$ref: '#/components/schemas/tax_exemption_id'
serial_numbers:
$ref: '#/components/schemas/serial_numbers'
batches:
$ref: '#/components/schemas/batches'
storages:
$ref: '#/components/schemas/storages'
item_custom_fields:
$ref: '#/components/schemas/item_custom_fields'
location_id:
$ref: '#/components/schemas/location_id'
gst_treatment:
$ref: '#/components/schemas/gst_treatment'
tax_treatment:
$ref: '#/components/schemas/tax_treatment'
gst_no:
$ref: '#/components/schemas/gst_no'
source_of_supply:
$ref: '#/components/schemas/source_of_supply'
destination_of_supply:
$ref: '#/components/schemas/destination_of_supply'
vendor_name:
description: Name of the vendor.
type: string
example: Molly
zip:
description: Zip code of the customer's billing address.
type: string
example: 10048
batches:
description: Batches for the line item. Create a new batch using <code>batch_number</code> or reference an existing batch using <code>batch_id</code>. Applicable only for items with batch tracking enabled.
type: array
items:
type: object
required:
- in_quantity
properties:
batch_id:
description: Unique identifier of a batch. Use when adding inward quantity to an existing batch or updating a batch.
type: string
example: '6780203000001066789'
batch_number:
description: Batch number. Required when creating a new batch.
type: string
example: BTC-TL-890
external_batch_number:
description: External batch number from the manufacturer. Applicable when creating a new batch.
type: string
example: MFR-TL-890
manufacturer_date:
description: Manufacturing date of the batch. Applicable when creating a new batch.
type: string
example: '2026-05-12'
expiry_date:
description: Expiration date of the batch. Applicable when creating a new batch.
type: string
example: '2026-12-24'
in_quantity:
description: Inward quantity for the batch.
type: number
format: float
example: 2
storages:
description: Bin/storage locations allocated for stock received against this batch.
type: array
x-node_available_in:
- Batch with Bin tracked items
items:
type: object
required:
- storage_id
- in_quantity
properties:
storage_id:
description: Unique identifier of the bin/storage location.
type: string
example: '6780203000001066003'
in_quantity:
description: Inward quantity into the bin.
type: number
format: float
example: 2
sub_total:
description: Sub Total of the Bill.
type: number
format: double
example: 30
approval-action-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
account_id:
description: Account ID of the item.
type: string
example: 4815000000035003
mark-as-open-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The bill has been marked as open.
readOnly: true
serial_numbers:
description: Serial numbers for the line item. Applicable only for items with serial tracking enabled.
type: array
items:
type: string
example: ARMP-0078
date:
description: Date of the Bill.
type: string
example: '2015-05-29'
paid_through_account_id:
description: ID for the account through which the payment is made.
type: string
example: 4815000000000361
item_total:
description: The total for the items.
type: number
format: double
example: 290
custom_fields:
description: Custom fields for a bill.
type: array
items:
type: object
properties:
customfield_id:
$ref: '#/components/schemas/customfield_id'
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
batches-update:
description: Batches for the line item. Create a new batch using <code>batch_number</code> or reference an existing batch using <code>batch_id</code>. Applicable only for items with batch tracking enabled.
type: array
items:
type: object
required:
- in_quantity
properties:
batch_id:
description: Unique identifier of a batch. Use when adding inward quantity to an existing batch or updating a batch.
type: string
example: '6780203000001066789'
batch_number:
description: Batch number. Required when creating a new batch.
type: string
example: BTC-TL-890
external_batch_number:
description: External batch number from the manufacturer. Applicable when creating a new batch.
type: string
example: MFR-TL-890
manufacturer_date:
description: Manufacturing date of the batch. Applicable when creating a new batch.
type: string
example: '2026-05-12'
expiry_date:
description: Expiration date of the batch. Applicable when creating a new batch.
type: string
example: '2026-12-24'
in_quantity:
description: Inward quantity for the batch.
type: number
format: float
example: 2
batch_in_id:
description: Unique identifier of the batch record. Applicable only when updating an existing batch entry.
type: string
example: '6780203000001066797'
storages:
description: Bin/storage locations allocated for stock received against this batch.
type: array
x-node_available_in:
- Batch with Bin tracked items
items:
type: object
required:
- storage_id
- in_quantity
properties:
storage_id:
description: Unique identifier of the bin/storage location.
type: string
example: '6780203000001066003'
storage_in_id:
description: Unique identifier of the storage record. Applicable only when updating an existing storage entry.
type: string
example: '6780203000001066792'
in_quantity:
description: Inward quantity into the bin.
type: number
format: float
example: 2
value:
description: Value of the Custom Field
type: string
example: Normal
reverse_charge_tax_id:
description: Reverse charge tax ID
type: string
example: 460000000038056
x-node_available_in:
- in
x-node_unavailable_in: []
currency_symbol:
description: The symbol for the selected currency.
type: string
example: $
unused_credits_payable_amount:
description: Unused credit payable amount.
type: number
format: double
example: 0
reverse_charge_tax_percentage:
description: Enter reverse charge percentage
type: number
format: double
example: 10
x-node_available_in:
- in
x-node_unavailable_in: []
open_purchaseorders_count:
description: Number of Purchase Orders that are associated with this Bill and open.
type: integer
example: 4
country:
description: Name of the country of the customer's billing address.
type: string
example: U.S.A
update-a-bill-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The Bill has been updated.
readOnly: true
bill:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
unused_credits_payable_amount:
$ref: '#/components/schemas/unused_credits_payable_amount'
status:
$ref: '#/components/schemas/status'
bill_number:
$ref: '#/components/schemas/bill_number'
date:
$ref: '#/components/schemas/date'
due_date:
$ref: '#/components/schemas/due_date'
reference_number:
$ref: '#/components/schemas/reference_number'
due_by_days:
$ref: '#/components/schemas/due_by_days'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
price_precision:
$ref: '#/components/schemas/price_precision'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
is_item_level_tax_calc:
$ref: '#/components/schemas/is_item_level_tax_calc'
custom_fields:
$ref: '#/components/schemas/custom_fields'
line_items:
$ref: '#/components/schemas/line_items'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
taxes:
$ref: '#/components/schemas/taxes'
vendor_credits_applied:
$ref: '#/components/schemas/vendor_credits_applied'
sub_total:
$ref: '#/components/schemas/sub_total'
tax_total:
$ref: '#/components/schemas/tax_total'
balance:
$ref: '#/components/schemas/balance'
billing_address:
$ref: '#/components/schemas/billing_address'
payments:
$ref: '#/components/schemas/payments'
vendor_credits:
$ref: '#/components/schemas/vendor_credits'
created_time:
$ref: '#/components/schemas/created_time'
last_modified_time:
$ref: '#/components/schemas/last_modified_time'
reference_id:
$ref: '#/components/schemas/reference_id'
notes:
$ref: '#/components/schemas/notes'
terms:
$ref: '#/components/schemas/terms'
attachment_name:
$ref: '#/components/schemas/attachment_name'
open_purchaseorders_count:
$ref: '#/components/schemas/open_purchaseorders_count'
gst_treatment:
$ref: '#/components/schemas/gst_treatment'
gst_no:
$ref: '#/components/schemas/gst_no'
source_of_supply:
$ref: '#/components/schemas/source_of_supply'
destination_of_supply:
$ref: '#/components/schemas/destination_of_supply'
is_pre_gst:
$ref: '#/components/schemas/is_pre_gst'
is_reverse_charge_applied:
$ref: '#/components/schemas/is_reverse_charge_applied'
bill_payment_id:
description: Bill payment ID
type: string
example: 4815000000046041
mark-as-void-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The bill has been marked as Void.
readOnly: true
status:
description: Status of the Bill.
type: string
example: paid
label:
description: Label of the Custom Field
type: string
hsn_or_sac:
description: Add HSN/SAC code for your goods/services
type: string
example: 80540
x-node_available_in:
- in
x-node_unavailable_in: []
quantity:
description: Quantity of the Item.
type: number
format: double
example: 5
storages-response:
description: Bin/storage locations tracked for the line item. Returned for items with bin tracking enabled.
type: array
items:
type: object
properties:
storage_id:
description: Unique identifier of the bin/storage location.
type: string
example: '6780203000000093226'
storage_name:
description: Display name of the bin/storage location.
type: string
example: Bin A2
in_quantity:
description: Inward quantity recorded against the bin.
type: number
format: float
example: 2
storage_in_id:
description: Unique identifier of the storage entry on the line item.
type: string
example: '6780203000001066795'
serial_numbers:
description: Serial numbers allocated to this bin.
type: array
x-node_available_in:
- Serial with Bin tracked items
items:
type: string
example: TC-IO-09
payments:
description: Payment details for the Bill.
type: array
items:
type: object
properties:
payment_id:
$ref: '#/components/schemas/payment_id'
bill_id:
$ref: '#/components/schemas/bill_id'
bill_payment_id:
$ref: '#/components/schemas/bill_payment_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
payment_number:
$ref: '#/components/schemas/payment_number'
description:
$ref: '#/components/schemas/description'
date:
$ref: '#/components/schemas/date'
reference_number:
$ref: '#/components/schemas/reference_number'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
amount:
$ref: '#/components/schemas/amount'
paid_through_account_id:
$ref: '#/components/schemas/paid_through_account_id'
paid_through_account_name:
$ref: '#/components/schemas/paid_through_account_name'
is_single_bill_payment:
$ref: '#/components/schemas/is_single_bill_payment'
billing_address:
description: Customer's billing address. It contains - <code>address</code>, <code>city</code>, <code>state</code>, <code>zip</code>, <code>country</code> and <code>fax</code>.
type: array
items:
type: object
properties:
address:
$ref: '#/components/schemas/address'
city:
$ref: '#/components/schemas/city'
state:
$ref: '#/components/schemas/state'
zip:
$ref: '#/components/schemas/zip'
country:
$ref: '#/components/schemas/country'
fax:
$ref: '#/components/schemas/fax'
bill-response:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
unused_credits_payable_amount:
$ref: '#/components/schemas/unused_credits_payable_amount'
status:
$ref: '#/components/schemas/status'
bill_number:
$ref: '#/components/schemas/bill_number'
date:
$ref: '#/components/schemas/date'
due_date:
$ref: '#/components/schemas/due_date'
reference_number:
$ref: '#/components/schemas/reference_number'
due_by_days:
$ref: '#/components/schemas/due_by_days'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/cur
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-bills-api-openapi.yml