OpenAPI Specification
openapi: 3.0.0
info:
title: batches purchaseorders 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: purchaseorders
description: PurchaseOrders Module
paths:
/purchaseorders:
x-mcp-group:
- Purchase Orders
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- purchaseorders
operationId: create_purchase_order
summary: Create a Purchase Order
description: Creates a new Purchase Order in Zoho Inventory. Description about extra parameter ignore_auto_number_generation - Ignore auto purchase order number generation for this Purchase order. This mandates the Purchase Order number to be entered. Allowed Values <code>true</code> and <code>false</code>.
parameters:
- name: ignore_auto_number_generation
in: query
description: Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number. Allowed values are <code> true </code> , <code> false </code>.
required: false
schema:
type: boolean
example: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-purchase-order-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-purchase-order-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.CREATE
get:
tags:
- purchaseorders
operationId: list_purchase_orders
summary: List all Purchase Orders
description: Lists all the Purchase Orders present 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-purchase-orders-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.READ
/purchaseorders/{purchaseorder_id}:
x-mcp-group:
- Purchase Orders
parameters:
- name: purchaseorder_id
in: path
required: true
description: Unique identifier of the purchase order.
schema:
type: string
example: 4815000000044972
- $ref: '#/components/parameters/organization_id'
get:
tags:
- purchaseorders
operationId: get_purchase_order
summary: Retrieve a Purchase Order
description: Retrieves the details for an existing Purchase Order.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/retrieve-a-purchase-order-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.READ
put:
tags:
- purchaseorders
operationId: update_purchase_order
summary: Update a Purchase Order
description: Updates a new Purchase Order in Zoho Inventory. Description about extra parameter ignore_auto_number_generation - Ignore auto Purchase order number generation for this Purchase Order. This mandates the Purchase Order number to be entered. Allowed Values <code>true</code> and <code>false</code>.
parameters:
- name: ignore_auto_number_generation
in: query
description: Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number. Allowed values are <code> true </code> , <code> false </code>.
required: false
schema:
type: boolean
example: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-purchase-order-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-purchase-order-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.UPDATE
delete:
tags:
- purchaseorders
operationId: delete_purchase_order
summary: Delete a Purchase Order
description: Deletes a Purchase Order from Zoho Inventory.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-purchase-order-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.DELETE
/purchaseorders/{purchaseorder_id}/status/issued:
x-mcp-group:
- Purchase Orders
parameters:
- name: purchaseorder_id
in: path
required: true
description: Unique identifier of the purchase order.
schema:
type: string
example: 4815000000044972
- $ref: '#/components/parameters/organization_id'
post:
tags:
- purchaseorders
operationId: mark_purchase_order_as_issued
summary: Mark as Issued
description: Marks a Purchase Order as Issued.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-issued-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.CREATE
/purchaseorders/{purchaseorder_id}/status/cancelled:
x-mcp-group:
- Purchase Orders
parameters:
- name: purchaseorder_id
in: path
required: true
description: Unique identifier of the purchase order.
schema:
type: string
example: 4815000000044972
- $ref: '#/components/parameters/organization_id'
post:
tags:
- purchaseorders
operationId: mark_purchase_order_as_cancelled
summary: Mark as Cancelled
description: Marks a Purchase Order as Cancelled.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-cancelled-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.CREATE
/purchaseorders/{purchaseorder_id}/submit:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: submit_purchaseorder
summary: Submit a purchase order for approval
description: Submit a purchase order for approval workflow.
parameters:
- name: purchaseorder_id
in: path
description: Unique ID of the purchase order.
required: true
schema:
type: string
example: '4815000000044972'
- $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.purchaseorders.UPDATE
/purchaseorders/{purchaseorder_id}/approve:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: approve_purchaseorder
summary: Approve a purchase order
description: Approve a submitted purchase order.
parameters:
- name: purchaseorder_id
in: path
description: Unique ID of the purchase order.
required: true
schema:
type: string
example: '4815000000044972'
- $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.purchaseorders.UPDATE
/purchaseorders/{purchaseorder_id}/reject:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: reject_purchaseorder
summary: Reject a purchase order
description: Reject a submitted purchase order.
parameters:
- name: purchaseorder_id
in: path
description: Unique ID of the purchase order.
required: true
schema:
type: string
example: '4815000000044972'
- $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.purchaseorders.UPDATE
/purchaseorders/{purchaseorder_id}/approve/final:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: final_approve_purchaseorder
summary: Final-approve a purchase order
description: Mark a submitted purchase order as final approved, bypassing the remaining approval sequence.
parameters:
- name: purchaseorder_id
in: path
description: Unique ID of the purchase order.
required: true
schema:
type: string
example: '4815000000044972'
- $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.purchaseorders.UPDATE
/purchaseorders/submit:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: bulk_submit_purchaseorders
summary: Bulk submit purchase orders for approval
description: Submit multiple purchase orders for approval workflow at once.
parameters:
- $ref: '#/components/parameters/organization_id'
- name: purchaseorder_ids
in: query
description: Comma-separated list of purchase order IDs to submit for approval.
required: true
schema:
type: string
example: 4815000000044972,4815000000044990
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.UPDATE
/purchaseorders/approve:
x-mcp-group:
- Purchase Orders
post:
tags:
- purchaseorders
operationId: bulk_approve_purchaseorders
summary: Bulk approve purchase orders
description: Approve multiple submitted purchase orders at once.
parameters:
- $ref: '#/components/parameters/organization_id'
- name: purchaseorder_ids
in: query
description: Comma-separated list of purchase order IDs to approve.
required: true
schema:
type: string
example: 4815000000044972,4815000000044990
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/approval-action-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.purchaseorders.UPDATE
components:
schemas:
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'
transaction_id:
description: Unique ID generated by the server for the transaction. This is used as an identifier.
type: string
example: 1232423434
terms:
description: Terms for the Purchase Order.
type: string
example: Terms and Conditions
expected_delivery_date:
description: Expected date of delivery for the items ordered.
type: string
example: '2015-05-28'
contact_persons_associated:
description: Contact Persons associated with the transaction.
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'
bills:
description: 'Bills raised for purchase order. Each bill contains these fields: <code>bill_id</code>, <code>bill_number</code>, <code>status</code>, <code>date</code>, <code>due_date</code>, <code>total</code>, <code>balance</code>.'
type: array
items:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
bill_number:
$ref: '#/components/schemas/bill_number'
status:
$ref: '#/components/schemas/status'
date:
$ref: '#/components/schemas/date'
due_date:
$ref: '#/components/schemas/due_date'
total:
$ref: '#/components/schemas/total'
balance:
$ref: '#/components/schemas/balance'
reverse_charge_tax_amount:
description: Tax amount for the reverse charge.
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'
date_formatted:
description: Indicates the date format.
type: string
example: 2015/05/28
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
item_id:
description: Unique ID generated by the server for the item. This is used as an identifier.
type: string
example: 4815000000044100
sub_total:
description: Sub total of the Purchase Order.
type: number
format: double
example: 244
comments:
description: History related to the purchase order.
type: array
items:
type: object
properties:
comment_id:
$ref: '#/components/schemas/comment_id'
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
commented_by:
$ref: '#/components/schemas/commented_by'
comment_type:
$ref: '#/components/schemas/comment_type'
date_description:
$ref: '#/components/schemas/date_description'
time:
$ref: '#/components/schemas/time'
operation_type:
$ref: '#/components/schemas/operation_type'
transaction_id:
$ref: '#/components/schemas/transaction_id'
transaction_type:
$ref: '#/components/schemas/transaction_type'
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
is_backorder:
description: This indicates whether it is a Back order or not.
type: boolean
example: false
retrieve-a-purchase-order-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
purchase_order:
type: object
properties:
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
purchaseorder_number:
$ref: '#/components/schemas/purchaseorder_number'
date:
$ref: '#/components/schemas/date'
expected_delivery_date:
$ref: '#/components/schemas/expected_delivery_date'
reference_number:
$ref: '#/components/schemas/reference_number'
status:
$ref: '#/components/schemas/status'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
contact_persons_associated:
$ref: '#/components/schemas/contact_persons_associated'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
delivery_date:
$ref: '#/components/schemas/delivery_date'
salesorder_id:
$ref: '#/components/schemas/salesorder_id'
is_drop_shipment:
$ref: '#/components/schemas/is_drop_shipment'
is_backorder:
$ref: '#/components/schemas/is_backorder'
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'
sub_total:
$ref: '#/components/schemas/sub_total'
tax_total:
$ref: '#/components/schemas/tax_total'
total:
$ref: '#/components/schemas/total'
taxes:
$ref: '#/components/schemas/taxes'
price_precision:
$ref: '#/components/schemas/price_precision'
pricebook_id:
$ref: '#/components/schemas/pricebook_id'
billing_address:
$ref: '#/components/schemas/billing_address'
notes:
$ref: '#/components/schemas/notes'
terms:
$ref: '#/components/schemas/terms'
ship_via:
$ref: '#/components/schemas/ship_via'
ship_via_id:
$ref: '#/components/schemas/ship_via_id'
attention:
$ref: '#/components/schemas/attention'
delivery_org_address_id:
$ref: '#/components/schemas/delivery_org_address_id'
delivery_customer_id:
$ref: '#/components/schemas/delivery_customer_id'
delivery_customer_name:
$ref: '#/components/schemas/delivery_customer_name'
delivery_address:
$ref: '#/components/schemas/delivery_address'
attachment_name:
$ref: '#/components/schemas/attachment_name'
can_send_in_mail:
$ref: '#/components/schemas/can_send_in_mail'
template_id:
$ref: '#/components/schemas/template_id'
template_name:
$ref: '#/components/schemas/template_name'
template_type:
$ref: '#/components/schemas/template_type'
created_time:
$ref: '#/components/schemas/created_time'
last_modified_time:
$ref: '#/components/schemas/last_modified_time'
purchasereceives:
$ref: '#/components/schemas/purchasereceives'
bills:
$ref: '#/components/schemas/bills'
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'
date:
description: Date of Purchase Order
type: string
example: '2015-05-28'
documents:
description: Purchase order can have files attached to them. Each attachment has the following attributes <code>can_send_in_mail</code>, <code>file_name</code>, <code>file_type</code>, <code>file_size_formatted</code>, <code>attachment_order</code>, <code>document_id</code>, <code>file_size</code>.
type: array
items:
type: object
properties:
can_send_in_mail:
$ref: '#/components/schemas/can_send_in_mail'
file_name:
$ref: '#/components/schemas/file_name'
file_type:
$ref: '#/components/schemas/file_type'
file_size_formatted:
$ref: '#/components/schemas/file_size_formatted'
attachment_order:
$ref: '#/components/schemas/attachment_order'
document_id:
$ref: '#/components/schemas/document_id'
file_size:
$ref: '#/components/schemas/file_size'
receive_id:
description: Unique ID generated by the server for the Purchase Receive. This is used as identifier.
type: string
example: 4815000000045035
purchase_rate:
description: Purchase Price of the line item.
type: number
format: double
example: 122
item_total:
description: Total of line item.
type: number
format: double
example: 244
custom_fields:
description: Custom fields for a purchaseorder.
type: array
items:
type: object
properties:
customfield_id:
$ref: '#/components/schemas/customfield_id'
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
value:
description: Value of the Custom Field
type: string
example: Normal
reverse_charge_tax_id:
description: Enter reverse charge tax ID
type: string
example: 460000000026068
currency_symbol:
description: The symbol for the selected currency.
type: string
example: $
is_drop_shipment:
description: Default is <code>FALSE</code>, in case of drop shipment value must be <code>TRUE</code>.
type: boolean
example: true
delivery_customer_id:
description: Customer ID for delivery address
type: string
example: 4815000000044066
contact_person_email:
description: Email ID of the Contact Person.
type: string
example: willsmith@bowmanfurniture.com
expected_delivery_date_formatted:
description: Indicates the date format.
type: string
example: 2015/05/28
reverse_charge_tax_percentage:
description: Enter reverse charge tax percentage
type: number
format: double
example: 10
x-node_available_in:
- in
x-node_unavailable_in: []
status_formatted:
description: Indicates the Format of the status.
type: string
example: Draft
mark-as-issued-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The purchase order has been marked as issued.
readOnly: true
document_id:
description: Unique ID generated by the server for the document. This is used as an identifier.
type: string
example: 16115000000096068
update-a-purchase-order-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
purchase_order:
type: object
properties:
purchaseorder_id:
$ref: '#/components/schemas/purchaseorder_id'
purchaseorder_number:
$ref: '#/components/schemas/purchaseorder_number'
date:
$ref: '#/components/schemas/date'
expected_delivery_date:
$ref: '#/components/schemas/expected_delivery_date'
reference_number:
$ref: '#/components/schemas/reference_number'
status:
$ref: '#/components/schemas/status'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
contact_persons_associated:
$ref: '#/components/schemas/contact_persons_associated'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
delivery_date:
$ref: '#/components/schemas/delivery_date'
salesorder_id:
$ref: '#/components/schemas/salesorder_id'
is_drop_shipment:
$ref: '#/components/schemas/is_drop_shipment'
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'
sub_total:
$ref: '#/components/schemas/sub_total'
tax_total:
$ref: '#/components/schemas/tax_total'
total:
$ref: '#/components/schemas/total'
taxes:
$ref: '#/components/schemas/taxes'
price_precision:
$ref: '#/components/schemas/price_precision'
pricebook_id:
$ref: '#/components/schemas/pricebook_id'
billing_address:
$ref: '#/components/schemas/billing_address'
notes:
$ref: '#/components/schemas/notes'
terms:
$ref: '#/components/schemas/terms'
ship_via:
$ref: '#/components/schemas/ship_via'
ship_via_id:
$ref: '#/components/schemas/ship_via_id'
attention:
$ref: '#/components/schemas/attention'
delivery_org_address_id:
$ref: '#/components/schemas/delivery_org_address_id'
delivery_customer_id:
$ref: '#/components/schemas/delivery_customer_id'
delivery_customer_name:
$ref: '#/components/schemas/delivery_customer_name'
delivery_address:
$ref: '#/components/schemas/delivery_address'
attachment_name:
$ref: '#/components/schemas/attachment_name'
can_send_in_mail:
$ref: '#/components/schemas/can_send_in_mail'
template_id:
$ref: '#/components/schemas/template_id'
template_name:
$ref: '#/components/schemas/template_name'
template_type:
$ref: '#/components/schemas/template_type'
created_time:
$ref: '#/components/schemas/created_time'
last_modified_time:
$ref: '#/components/schemas/last_modified_time'
purchasereceives:
$ref: '#/components/schemas/purchasereceives'
bills:
$ref: '#/components/schemas/bills'
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'
country:
description: Name of the country of the customer's billing address.
type: string
example: U.S.A
status:
description: Status of Purchase Order.
type: string
example: Partially_Received
create-a-purchase-order-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
purchase_order:
$ref: '#/components/schemas/purchase_order-response'
label:
description: Label of the Custom Field
type: string
phone:
description: Phone Number of the Contact Person.
type: string
example: +1-925-921-9201
transaction_type:
description: Indicates the type of the transaction.
type: string
example: purchaseorder
hsn_or_sac:
description: HSN or SAC Code for the Item
type: string
x-node_available_in:
- in
x-node_unavailable_in: []
attention:
description: Name of the person, whose attention is required.
type: string
example: Tony
quantity:
description: Quantity of the line item.
type: number
format: double
example: 2
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'
quantity_received:
description: Quantity invoiced of the line item.
type: number
format: double
example: 2
tax_percentage:
description: Percentage of the tax.
type: number
format: double
example: 12
name:
description: Name of the line item.
type: string
example: Laptop-white/15inch/dell
bill_id:
description: Unique ID generated by the server. This is used as identifier.
type: string
example: 4815000000045067
bill_number:
description: Bill number of Purchase Order.
type: string
example: BL-00002
list-all-pu
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-purchaseorders-api-openapi.yml