OpenAPI Specification
openapi: 3.0.0
info:
title: batches putaways 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: putaways
description: Putaways Module
paths:
/putaways:
x-mcp-group:
- Putaways
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- putaways
operationId: create_putaway
summary: Create a putaway
description: Creates a new putaway transaction in Zoho Inventory.
parameters:
- name: ignore_auto_number_generation
in: query
description: When auto number generation is enabled for putaways, set to true to supply your own putaway number instead of using the auto-generated value. Default is false.
required: false
schema:
type: boolean
example: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-putaway-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-putaway-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.CREATE
get:
tags:
- putaways
operationId: list_putaways
summary: List all putaways
description: Lists putaway transactions with optional filters and pagination.
parameters:
- name: page
in: query
description: Page number to fetch. Default is 1.
required: false
schema:
type: integer
default: 1
example: 1
- name: per_page
in: query
description: Number of records per page. Default is 200.
required: false
schema:
type: integer
default: 200
example: 200
- name: sort_column
in: query
description: Column used for sorting the list.
required: false
schema:
type: string
example: created_time
- name: sort_order
in: query
description: Sort order. A for ascending, D for descending.
required: false
schema:
type: string
enum:
- A
- D
example: D
- name: filter_by
in: query
description: Filter expression supported by the putaway list view.
required: false
schema:
type: string
- name: customview_id
in: query
description: Custom view ID to apply.
required: false
schema:
type: integer
format: int64
- name: putaway_number
in: query
description: Search by putaway number.
required: false
schema:
type: string
- name: date
in: query
description: Filter by putaway date (yyyy-mm-dd).
required: false
schema:
type: string
- name: warehouse_id
in: query
description: Filter by warehouse ID.
required: false
schema:
type: integer
format: int64
- name: location_id
in: query
description: Filter by location (branch) ID when locations are enabled.
required: false
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-putaways-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.READ
/putaways/{putaway_id}:
x-mcp-group:
- Putaways
parameters:
- name: putaway_id
in: path
required: true
description: Unique identifier of the putaway.
schema:
type: string
example: '4815000000044895'
- $ref: '#/components/parameters/organization_id'
get:
tags:
- putaways
operationId: get_putaway
summary: Retrieve a putaway
description: Fetches details of an existing putaway, including line items.
parameters:
- name: include
in: query
description: When set to HTML, additional HTML content may be included in the response when supported.
required: false
schema:
type: string
- name: print
in: query
description: 'Export putaway pdf with default print option. Allowed Values: <code>true</code>, <code>false</code>'
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-a-putaway-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.READ
put:
tags:
- putaways
operationId: update_putaway
summary: Update a putaway
description: Updates an existing putaway transaction.
parameters:
- name: ignore_auto_number_generation
in: query
description: When auto number generation is enabled for putaways, set to true to keep a manually supplied putaway number. Default is false.
required: false
schema:
type: boolean
example: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-putaway-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-putaway-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.UPDATE
delete:
tags:
- putaways
operationId: delete_putaway
summary: Delete a putaway
description: Deletes an existing putaway transaction.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-putaway-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.DELETE
/putaways/{putaway_id}/comments:
x-mcp-group:
- Putaways
parameters:
- name: putaway_id
in: path
required: true
description: Unique identifier of the putaway.
schema:
type: string
example: '4815000000044895'
- $ref: '#/components/parameters/organization_id'
get:
tags:
- putaways
operationId: list_putaway_comments
summary: List comments for a putaway
description: Returns all comments recorded on a putaway.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-putaway-comments-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.READ
/putaways/{putaway_id}/attachment:
x-mcp-group:
- Putaways
parameters:
- name: putaway_id
in: path
required: true
description: Unique identifier of the putaway.
schema:
type: string
example: '4815000000044895'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- putaways
operationId: add_putaway_attachment
summary: Attach files to a putaway
description: Uploads one or more files and associates them with the putaway.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
attachment:
type: string
format: binary
description: File to attach.
doc:
type: string
description: Optional JSON metadata for the document.
totalFiles:
type: integer
description: Number of file parts included in this multipart request when the client sends multiple attachments.
document_ids:
type: string
description: Comma-separated existing document IDs when applicable.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/putaway-attachment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.CREATE
/putaways/{putaway_id}/documents/{document_id}:
x-mcp-group:
- Putaways
parameters:
- name: putaway_id
in: path
required: true
description: Unique identifier of the putaway.
schema:
type: string
example: '4815000000044895'
- name: document_id
in: path
required: true
description: Unique identifier of the document.
schema:
type: string
example: '4815000000044897'
- $ref: '#/components/parameters/organization_id'
get:
tags:
- putaways
operationId: get_putaway_document
summary: Download a putaway document
description: Returns the binary content of an attached document (image or PDF).
parameters:
- name: image_size
in: query
description: Preferred image size when the service returns a rasterized preview.
required: false
schema:
type: string
enum:
- xlarge
- large
- small
- tiny
- name: print
in: query
description: 'Allowed Values: <code>true</code>, <code>false</code>'
required: false
schema:
type: boolean
- name: inline
in: query
description: When true, the response may be suitable for inline display in a browser when supported.
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/pdf:
schema:
type: string
format: binary
examples:
binary_body:
summary: Raw document bytes
description: Response is binary PDF or image data, not a JSON envelope.
value: << binary body >>
image/jpeg:
schema:
type: string
format: binary
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.READ
delete:
tags:
- putaways
operationId: delete_putaway_document
summary: Remove an attachment from a putaway
description: Deletes or unlinks a document from the putaway.
parameters:
- name: un_associate
in: query
description: When true, only dissociates the file without deleting the underlying document when supported.
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-putaway-document-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.putaway.DELETE
/settings/putaways:
x-mcp-group:
- Putaways
parameters:
- $ref: '#/components/parameters/organization_id'
get:
tags:
- putaways
operationId: get_putaway_settings
summary: Get putaway auto number generation settings
description: Returns auto number generation preferences for putaways.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-putaway-settings-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.settings.READ
components:
schemas:
create-a-putaway-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
readOnly: true
putaway:
$ref: '#/components/schemas/putaway-response'
page_context:
type: object
description: Pagination and list context for the current result set.
properties:
page:
type: integer
example: 1
per_page:
type: integer
example: 200
has_more_page:
type: boolean
report_name:
type: string
applied_filter:
type: string
sort_column:
type: string
sort_order:
type: string
list-putaway-comments-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
readOnly: true
comments:
type: array
items:
$ref: '#/components/schemas/putaway-comment'
get-a-putaway-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
putaway:
$ref: '#/components/schemas/putaway-response'
delete-a-putaway-response:
type: object
description: Returned when a putaway is deleted.
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Putaway deleted successfully.
readOnly: true
putaway-attachment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
readOnly: true
document:
$ref: '#/components/schemas/putaway-document-attachment'
putaway-line-serial-node:
type: object
description: Serial number row for a putaway line when serial tracking is enabled.
properties:
serialnumber_id:
type: integer
format: int64
description: Serial number master record ID.
serial_number:
type: string
description: Serial code.
status:
type: string
description: Serial status when returned by the service.
list-putaways-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
putaways:
type: array
items:
$ref: '#/components/schemas/putaway-list-row'
page_context:
$ref: '#/components/schemas/page_context'
get-putaway-settings-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
readOnly: true
putaway_settings:
$ref: '#/components/schemas/putaway-settings'
putaway-response:
type: object
properties:
putaway_id:
type: integer
format: int64
putaway_number:
type: string
date:
type: string
notes:
type: string
created_by_id:
type: integer
format: int64
created_by_name:
type: string
warehouse_id:
type: integer
format: int64
warehouse_name:
type: string
location_id:
type: integer
format: int64
location_name:
type: string
html_string:
type: string
comments:
type: array
items:
$ref: '#/components/schemas/putaway-comment'
line_items:
type: array
items:
$ref: '#/components/schemas/putaway-line-item-response'
documents:
type: array
description: Attachments on the putaway when returned by the service.
items:
$ref: '#/components/schemas/putaway-document-attachment'
putaway-line-item-request:
type: object
required:
- item_id
- quantity_transferred
properties:
line_item_id:
type: integer
format: int64
description: Line item ID returned by the server. Required on update when modifying existing line items.
item_id:
type: integer
format: int64
description: Item (product) ID for the line. Required for every line item (same role as <code>item_id</code> on transfer order line items).
description:
type: string
description: Line-level description or notes for the item. Optional.
quantity_transferred:
type: number
format: double
description: Quantity put away for this line. Required for every line item (same role as <code>quantity_transfer</code> on transfer orders).
serial_numbers:
type: array
description: Serial number details when serial tracking is enabled.
items:
$ref: '#/components/schemas/putaway-line-serial-node'
batches:
type: array
description: Batch details when batch tracking is enabled.
items:
$ref: '#/components/schemas/putaway-line-batch-node'
storages:
type: array
description: Storage bin allocations when storage tracking is enabled.
items:
$ref: '#/components/schemas/putaway-line-storage-node'
putaway-document-attachment:
type: object
description: File attached to a putaway (DocumentDetailsForEntity).
properties:
document_id:
type: integer
format: int64
description: Attachment document ID; use with GET/DELETE `/putaways/{putaway_id}/documents/{document_id}`.
file_name:
type: string
description: Original file name.
file_type:
type: string
description: MIME or file type classification.
file_size:
type: integer
format: int64
description: File size in bytes.
file_size_formatted:
type: string
description: Human-readable file size.
update-a-putaway-request:
$ref: '#/components/schemas/create-a-putaway-request'
putaway-settings:
type: object
properties:
auto_generate:
type: boolean
description: Whether putaway numbers are auto-generated.
prefix_string:
type: string
description: Prefix for auto-generated putaway numbers.
next_number:
type: string
description: Next number in the auto-number sequence.
update-a-putaway-response:
$ref: '#/components/schemas/get-a-putaway-response'
putaway-list-row:
type: object
properties:
putaway_id:
type: integer
format: int64
putaway_number:
type: string
date:
type: string
notes:
type: string
warehouse_id:
type: integer
format: int64
warehouse_name:
type: string
location_id:
type: integer
format: int64
location_name:
type: string
has_attachment:
type: boolean
created_time:
type: string
last_modified_time:
type: string
delete-a-putaway-document-response:
type: object
description: Returned when a document is removed from a putaway.
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Your file is no longer attached to the Putaway.
readOnly: true
putaway-line-item-response:
type: object
properties:
line_item_id:
type: integer
format: int64
item_id:
type: integer
format: int64
name:
type: string
sku:
type: string
unit:
type: string
image_document_id:
type: integer
format: int64
description:
type: string
quantity_transferred:
type: number
format: double
track_serial_number:
type: boolean
track_batch_number:
type: boolean
serial_numbers:
type: array
items:
$ref: '#/components/schemas/putaway-line-serial-node'
batches:
type: array
items:
$ref: '#/components/schemas/putaway-line-batch-node'
is_combo_product:
type: boolean
storages:
type: array
items:
$ref: '#/components/schemas/putaway-line-storage-node'
is_storage_location_enabled:
type: boolean
putaway-line-storage-node:
type: object
description: Storage-bin allocation for a putaway line when storage tracking is enabled.
properties:
storage_id:
type: integer
format: int64
description: Storage location ID.
quantity:
type: number
format: double
description: Quantity put away into this storage for the line.
putaway-comment:
type: object
properties:
comment_id:
type: integer
format: int64
putaway_id:
type: integer
format: int64
description:
type: string
commented_by_id:
type: integer
format: int64
commented_by:
type: string
comment_type:
type: string
date:
type: string
date_description:
type: string
time:
type: string
operation_type:
type: string
putaway-line-batch-node:
type: object
description: One batch allocation on a putaway line when batch tracking is enabled (see server BatchNumberCreate / BatchNumberEdit).
properties:
batch_id:
type: integer
format: int64
description: Existing inventory batch ID when selecting stock from an existing batch.
batch_in_id:
type: integer
format: int64
description: Batch-in row reference when supplied by the client.
batch_number:
type: string
description: Batch number for a new batch line when not using an existing batch_id.
manufacturer_batch_number:
type: string
description: Manufacturer or external batch reference.
manufactured_date:
type: string
description: Manufacturing date (yyyy-mm-dd).
expiry_date:
type: string
description: Expiry date (yyyy-mm-dd).
in_quantity:
type: number
format: double
description: Quantity for this batch when the line quantity is split across batches.
sales_rate:
type: number
format: double
description: Selling rate for the batch when batch pricing is enabled.
label_rate:
type: number
format: double
description: Label (MRP) rate for the batch when applicable.
balance_quantity:
type: number
format: double
readOnly: true
description: On read, returns the remaining quantity in the batch.
status:
type: string
readOnly: true
description: On read, batch status when returned by the service.
create-a-putaway-request:
type: object
required:
- date
- line_items
properties:
putaway_number:
type: string
description: Putaway number; optional when auto-generation is enabled.
date:
type: string
description: Transaction date (yyyy-mm-dd).
warehouse_id:
type: integer
format: int64
description: Warehouse ID when warehouses are enabled.
location_id:
type: integer
format: int64
description: Location (branch) ID when locations are enabled.
notes:
type: string
description: Internal notes for the putaway.
line_items:
type: array
description: 'A putaway can contain multiple line items. Each object must include <code>item_id</code> and <code>quantity_transferred</code>. Optional fields: <code>line_item_id</code> (required on update for existing lines), <code>description</code>, <code>serial_numbers</code>, <code>batches</code>, and <code>storages</code> when serial, batch, or bin storage tracking applies in your organization.'
items:
$ref: '#/components/schemas/putaway-line-item-request'
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