openapi: 3.0.0
info:
title: batches 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: batches
description: Batches Module
paths:
/items/batches:
x-mcp-group:
- Batches
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- batches
operationId: create_a_batch
summary: Create a batch
description: Create a new batch for an item that has batch tracking enabled.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-batch-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-batch-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.CREATE
get:
tags:
- batches
operationId: list_batches
summary: List all batches
description: List all batches available for a given item.
parameters:
- name: item_id
in: query
description: Unique identifier of the item to fetch batches for.
required: true
schema:
type: string
example: '6780203000000167467'
- name: include_empty_batches
in: query
description: Include batches that have zero quantity. Allowed values <code>true</code> and <code>false</code>.
schema:
type: boolean
example: false
- name: warehouse_id
in: query
description: Filter batches by warehouse ID.
schema:
type: string
example: '6780203000000093215'
- name: location_id
in: query
description: Filter batches by location ID.
schema:
type: string
example: '6780203000000093215'
- name: batch_ids
in: query
description: Comma-separated list of batch IDs to filter the response.
schema:
type: string
example: 6780203000000176162,6780203000000176163
- name: search_text
in: query
description: Search batches by batch number or manufacturer batch number.
schema:
type: string
example: BATCH
- name: status
in: query
description: Filter batches by status. Allowed values <code>active</code> and <code>inactive</code>.
schema:
type: string
example: active
- name: filter_by
in: query
description: Filter batches by status, expiry, type, or stock. For example <code>Status.All</code>, <code>Expiry.Expired</code>, <code>Stock.Empty</code>.
schema:
type: string
example: Status.All
- name: sort_column
in: query
description: Column to sort the response by. Allowed values <code>batch_number</code>, <code>external_batch_number</code>, <code>manufacturer_batch_number</code>, <code>manufactured_date</code>, <code>expiry_date</code>, <code>sales_rate</code>, and <code>label_rate</code>.
schema:
type: string
default: batch_number
example: batch_number
- name: sort_order
in: query
description: Order of sorting. Allowed values <code>A</code> for ascending and <code>D</code> for descending.
schema:
type: string
default: A
example: A
- name: page
in: query
description: Page number to be fetched. Default value is 1.
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.
schema:
type: integer
default: 200
example: 200
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-all-batches-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.READ
delete:
tags:
- batches
operationId: bulk_delete_batches
summary: Bulk delete batches
description: Delete multiple batches in a single request. Batches with associated transactions cannot be deleted.
parameters:
- name: batch_ids
in: query
required: true
description: Comma-separated list of batch IDs to delete.
schema:
type: string
example: 6780203000000176162,6780203000000176163
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-delete-batches-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.DELETE
/items/batches/{batch_id}:
x-mcp-group:
- Batches
parameters:
- name: batch_id
in: path
required: true
description: Unique identifier of the batch.
schema:
type: string
example: '6780203000000176162'
- $ref: '#/components/parameters/organization_id'
get:
tags:
- batches
operationId: retrieve_a_batch
summary: Retrieve a batch
description: Fetch the details of a specific batch.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/retrieve-a-batch-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.READ
put:
tags:
- batches
operationId: update_a_batch
summary: Update a batch
description: Update the details of an existing batch.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-batch-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-batch-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.UPDATE
delete:
tags:
- batches
operationId: delete_a_batch
summary: Delete a batch
description: Delete a single batch. The batch must not have any associated transactions.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-batch-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.DELETE
/items/batches/{batch_id}/active:
x-mcp-group:
- Batches
parameters:
- name: batch_id
in: path
required: true
description: Unique identifier of the batch.
schema:
type: string
example: '6780203000000176162'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- batches
operationId: mark_batch_as_active
summary: Mark a batch as active
description: Mark a specific batch as active.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-a-batch-as-active-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.CREATE
/items/batches/{batch_id}/inactive:
x-mcp-group:
- Batches
parameters:
- name: batch_id
in: path
required: true
description: Unique identifier of the batch.
schema:
type: string
example: '6780203000000176162'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- batches
operationId: mark_batch_as_inactive
summary: Mark a batch as inactive
description: Mark a specific batch as inactive.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-a-batch-as-inactive-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.CREATE
/items/batches/active:
x-mcp-group:
- Batches
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- batches
operationId: mark_batches_as_active
summary: Mark batches as active
description: Mark multiple batches as active in a single request.
parameters:
- name: batch_ids
in: query
required: true
description: Comma-separated list of batch IDs to mark as active.
schema:
type: string
example: 6780203000000176162,6780203000000176163
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-batches-as-active-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.CREATE
/items/batches/inactive:
x-mcp-group:
- Batches
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- batches
operationId: mark_batches_as_inactive
summary: Mark batches as inactive
description: Mark multiple batches as inactive in a single request.
parameters:
- name: batch_ids
in: query
required: true
description: Comma-separated list of batch IDs to mark as inactive.
schema:
type: string
example: 6780203000000176162,6780203000000176163
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-batches-as-inactive-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.items.CREATE
components:
schemas:
status:
description: Status of the batch. Allowed values <code>active</code> and <code>inactive</code>.
type: string
example: active
batch-response:
description: Details of a batch.
type: object
properties:
batch_id:
$ref: '#/components/schemas/batch_id'
item_id:
$ref: '#/components/schemas/item_id'
batch_number:
$ref: '#/components/schemas/batch_number'
manufacturer_batch_number:
$ref: '#/components/schemas/manufacturer_batch_number'
manufactured_date:
$ref: '#/components/schemas/manufactured_date'
expiry_date:
$ref: '#/components/schemas/expiry_date'
balance_quantity:
$ref: '#/components/schemas/balance_quantity'
status:
$ref: '#/components/schemas/status'
batch_custom_fields:
$ref: '#/components/schemas/batch_custom_fields'
label:
description: Label of the custom field.
type: string
example: Lot Code
external_batch_number:
description: External batch number from the manufacturer.
type: string
example: MFR-BTC-8900
balance_quantity:
description: Quantity currently available in the batch.
type: number
format: float
example: 0
manufacturer_batch_number:
description: Manufacturer-provided batch number.
type: string
example: MFR-BTC-8900
associated_locations:
description: Locations where stock for this batch is available, with the inward and balance quantity at each location.
type: array
items:
type: object
properties:
location_id:
$ref: '#/components/schemas/location_id'
in_quantity:
$ref: '#/components/schemas/in_quantity'
balance_quantity:
$ref: '#/components/schemas/balance_quantity'
create-a-batch-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The batch has been created.
readOnly: true
batch:
$ref: '#/components/schemas/batch-response'
item_id:
description: Unique identifier of the item the batch belongs to.
type: string
example: '6780203000001003147'
mark-a-batch-as-inactive-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The batch has been marked as inactive.
readOnly: true
manufactured_date:
description: Manufacturing date of the batch.
type: string
example: '2026-05-12'
retrieve-a-batch-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
batch:
$ref: '#/components/schemas/batch-response'
update-a-batch-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The batch has been updated.
readOnly: true
batch:
$ref: '#/components/schemas/batch-response'
label_rate:
description: Label rate of the batch.
type: number
format: float
example: 50
x-node_available_in:
- Batch Price enabled
sales_rate:
description: Sales rate of the batch.
type: number
format: float
example: 50.4
x-node_available_in:
- Batch Price enabled
in_quantity:
description: Quantity received into the batch when stock was added.
type: number
format: float
example: 0
internal_batch_number:
description: Internal batch number generated by the system.
type: string
example: ''
mark-batches-as-inactive-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The selected batches have been marked as inactive.
readOnly: true
list-all-batches-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
batches:
type: array
items:
$ref: '#/components/schemas/list-batches-item'
mark-a-batch-as-active-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The batch has been marked as active.
readOnly: true
value:
description: Value of the custom field.
type: string
example: LC-001
batch_number:
description: Batch number.
type: string
example: BTC-8900
custom_field_id:
description: Unique identifier of the custom field.
type: string
example: '6780203000000176175'
location_id:
description: Unique identifier of the location associated with the batch.
type: string
example: '6780203000000093215'
create-a-batch-request:
required:
- item_id
- batch_number
type: object
properties:
item_id:
$ref: '#/components/schemas/item_id'
batch_number:
$ref: '#/components/schemas/batch_number'
manufacturer_batch_number:
$ref: '#/components/schemas/manufacturer_batch_number'
manufactured_date:
$ref: '#/components/schemas/manufactured_date'
expiry_date:
$ref: '#/components/schemas/expiry_date'
sales_rate:
$ref: '#/components/schemas/sales_rate'
label_rate:
$ref: '#/components/schemas/label_rate'
batch_custom_fields:
$ref: '#/components/schemas/batch_custom_fields'
delete-a-batch-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The batch has been deleted.
readOnly: true
batch_id:
description: Unique identifier of the batch.
type: string
example: '6780203000001066694'
expiry_date:
description: Expiration date of the batch.
type: string
example: '2026-10-15'
bulk-delete-batches-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The selected batches have been deleted.
readOnly: true
list-batches-item:
description: Details of a batch as returned in the list batches response.
type: object
properties:
batch_id:
$ref: '#/components/schemas/batch_id'
batch_in_id:
$ref: '#/components/schemas/batch_in_id'
batch_number:
$ref: '#/components/schemas/batch_number'
internal_batch_number:
$ref: '#/components/schemas/internal_batch_number'
external_batch_number:
$ref: '#/components/schemas/external_batch_number'
manufacturer_batch_number:
$ref: '#/components/schemas/manufacturer_batch_number'
manufacturer_date:
$ref: '#/components/schemas/manufacturer_date'
manufactured_date:
$ref: '#/components/schemas/manufactured_date'
expiry_date:
$ref: '#/components/schemas/expiry_date'
in_quantity:
$ref: '#/components/schemas/in_quantity'
balance_quantity:
$ref: '#/components/schemas/balance_quantity'
balance_quantity_unit:
$ref: '#/components/schemas/balance_quantity_unit'
location_id:
$ref: '#/components/schemas/location_id'
associated_locations:
$ref: '#/components/schemas/associated_locations'
batch_custom_fields:
$ref: '#/components/schemas/batch_custom_fields'
status:
$ref: '#/components/schemas/status'
batch_in_id:
description: Unique identifier of the inward batch entry created when stock was received.
type: string
example: '6780203000001003281'
balance_quantity_unit:
description: Unit of measurement for the balance quantity.
type: string
example: ''
mark-batches-as-active-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The selected batches have been marked as active.
readOnly: true
update-a-batch-request:
type: object
properties:
batch_number:
$ref: '#/components/schemas/batch_number'
manufacturer_batch_number:
$ref: '#/components/schemas/manufacturer_batch_number'
manufactured_date:
$ref: '#/components/schemas/manufactured_date'
expiry_date:
$ref: '#/components/schemas/expiry_date'
sales_rate:
$ref: '#/components/schemas/sales_rate'
label_rate:
$ref: '#/components/schemas/label_rate'
batch_custom_fields:
$ref: '#/components/schemas/batch_custom_fields'
manufacturer_date:
description: Manufacturing date of the batch. Legacy alias retained for backward compatibility; prefer <code>manufactured_date</code>.
type: string
example: '2026-05-12'
batch_custom_fields:
description: Custom fields configured for the batch.
type: array
items:
type: object
properties:
custom_field_id:
$ref: '#/components/schemas/custom_field_id'
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
parameters:
organization_id:
name: organization_id
description: ID of the organization
in: query
required: true
schema:
type: string
example: '10234695'
securitySchemes:
Zoho_Auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoInventory.items.CREATE: Create Items
ZohoInventory.items.READ: Read Items
ZohoInventory.items.UPDATE: Update Items
ZohoInventory.items.DELETE: Delete Items