Zoho Inventory · Schema
Picklists
Picklists help teams track and manage the picking of items for sales orders and purchase returns. You can create picklists, assign them to staff, track picking progress by status, and add comments for collaboration.
Inventory ManagementWarehousingSales OrdersPurchase OrdersStock AdjustmentShipmentsItemsE-commerce
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Picklists",
"description": "Picklists help teams track and manage the picking of items for sales orders and purchase returns. You can create picklists, assign them to staff, track picking progress by status, and add comments for collaboration.",
"definitions": {
"picklist_id": {
"description": "Unique ID generated by the server for the picklist.",
"type": "string",
"readOnly": true,
"example": "130426000000810001"
},
"picklist_number": {
"description": "Unique number assigned to the picklist. Auto-generated unless overridden.",
"type": "string",
"maxLength": 50,
"example": "Pick-00001"
},
"picklist-line-item": {
"description": "A line item in a picklist representing one item to be picked.\n\nThe fields depend on `group_by`:\n\n- **`group_by=none` (flat)** - every pick-related fields below (item, quantities, tracking, storages, status, and similar) is added directly on the line item. `mapping_entity_details` is **not** used.\n- **`group_by=item` or `sales_order` (grouped)** - only the grouping fields (`line_item_id`, `assignee_id`, `assignee_name`, `parent_id`, `parent_name`, item-summary fields, and for `sales_order` also `customer_name`, `order_date`, `shipment_date`, `delivery_method`) are added on the parent. The actual per-pick fields (quantities, status, storages, tracking) are added inside `mapping_entity_details`.\n\n> Grouping is applicable only for sales-order picklists. Purchase-return picklists are always flat (`group_by=none`).\n",
"type": "object",
"properties": {
"line_item_id": {
"description": "Unique ID of the line item",
"type": "string",
"example": "130426000000810011"
},
"parent_id": {
"description": "Grouping entity ID: the `item_id` for `group_by=item`, or the `salesorder_id` for `group_by=sales_order`. Returned only for grouped picklists.",
"type": "string",
"example": "130426000000664040"
},
"parent_name": {
"description": "Display name of the grouping entity (item name or sales order number). Returned only for grouped picklists.",
"type": "string",
"example": "Office Chair"
},
"customer_name": {
"description": "Customer name of the grouped sales order. Returned only when `group_by=sales_order`.",
"type": "string",
"example": "Acme Corp"
},
"order_date": {
"description": "Date of the grouped sales order. Returned only when `group_by=sales_order`.",
"type": "string",
"format": "date",
"example": "2024-01-12"
},
"shipment_date": {
"description": "Expected shipment date of the grouped sales order. Returned only when `group_by=sales_order`.",
"type": "string",
"format": "date",
"example": "2024-01-18"
},
"delivery_method": {
"description": "Delivery method of the grouped sales order. Returned only when `group_by=sales_order`.",
"type": "string",
"example": "FedEx"
},
"assignee_id": {
"description": "ID of the user assigned to pick this line item. For grouped picklists this is the picker assigned to the entire group.",
"type": "string",
"example": "130426000000664060"
},
"assignee_name": {
"description": "Name of the assigned user.",
"type": "string",
"example": "John Doe"
},
"mapping_entity_details": {
"description": "Child pick entries grouped under this parent line item. Returned **only** for grouped picklists (`group_by=item` or `sales_order`). For `group_by=none`, this field is omitted and pick details are returned directly on the line item.",
"type": "array",
"items": {
"$ref": "#/components/schemas/picklist-line-item-mapping"
}
},
"salesorder_id": {
"description": "ID of the associated sales order. Returned for `group_by=none` and `group_by=sales_order`.",
"type": "string",
"example": "130426000000700001"
},
"salesorder_number": {
"description": "Number of the associated sales order. Returned only for `group_by=none`.",
"type": "string",
"example": "SO-00001"
},
"purchasereturn_id": {
"description": "ID of the associated purchase return. Returned for purchase-return picklists.",
"type": "string",
"example": "130426000000720001"
},
"purchasereturn_number": {
"description": "Number of the associated purchase return. Returned for purchase-return picklists.",
"type": "string",
"example": "PR-00001"
},
"so_line_item_id": {
"description": "ID of the underlying sales order line item. Returned only for `group_by=none`.",
"type": "string",
"example": "130426000000700011"
},
"pr_line_item_id": {
"description": "ID of the underlying purchase return line item. Returned for purchase-return picklists.",
"type": "string",
"example": "130426000000720011"
},
"item_id": {
"description": "ID of the item to be picked. Returned only for `group_by=none`.",
"type": "string",
"example": "130426000000664040"
},
"name": {
"description": "Name of the item. Returned only for `group_by=none`.",
"type": "string",
"example": "Office Chair"
},
"sku": {
"description": "SKU of the item. Returned for `group_by=none` and `group_by=item`.",
"type": "string",
"example": "CHAIR-001"
},
"is_storage_location_enabled": {
"description": "Whether storage location tracking is enabled for this item. Returned only when Zoho Inventory and storage tracking are enabled, and `group_by` is `none` or `item`.",
"type": "boolean",
"example": true
},
"is_combo_product": {
"description": "Whether the item is a composite/combo product. Returned only when Zoho Inventory is enabled, and `group_by` is `none` or `item`.",
"type": "boolean",
"example": false
},
"unit": {
"description": "Usage unit of the line item. Returned only for `group_by=none`.",
"type": "string",
"example": "pcs"
},
"base_unit": {
"description": "Base unit configured on the item. Returned only for `group_by=none`.",
"type": "string",
"example": "pcs"
},
"base_unit_id": {
"description": "ID of the base unit. Returned only when unit conversion is enabled and `group_by=none`.",
"type": "string",
"example": "130426000000900020"
},
"unit_conversion_id": {
"description": "ID of the unit conversion applied. Returned only when unit conversion is enabled and `group_by=none`.",
"type": "string",
"example": "130426000000900001"
},
"conversion_rate": {
"description": "Unit conversion rate. Returned only when unit conversion is enabled and `group_by=none`.",
"type": "number",
"example": 1
},
"quantity_decimal_place": {
"description": "Number of decimal places used for quantity values on this line item. Returned only for `group_by=none`.",
"type": "integer",
"example": 2
},
"description": {
"description": "Description of the line item. Returned only for `group_by=none`.",
"type": "string",
"example": "Ergonomic mesh office chair."
},
"image_name": {
"description": "File name of the item image. Returned only for `group_by=none`.",
"type": "string",
"example": "chair.png"
},
"image_type": {
"description": "File type of the item image. Returned only for `group_by=none`.",
"type": "string",
"example": "png"
},
"image_document_id": {
"description": "Document ID of the item image. Returned only for `group_by=none`.",
"type": "string",
"example": "130426000000910001"
},
"quantity_ordered": {
"description": "Quantity ordered on the underlying sales order line item, normalized to the picking unit. Returned only for `group_by=none`.",
"type": "number",
"example": 10
},
"quantity_returned": {
"description": "Quantity on the underlying purchase return line item. Returned for purchase-return picklists.",
"type": "number",
"example": 5
},
"so_quantity_ordered": {
"description": "Total quantity ordered on the underlying sales order line item (in the SO unit). Returned only for `group_by=none`.",
"type": "number",
"example": 10
},
"pr_quantity_returned": {
"description": "Total quantity on the underlying purchase return line item. Returned for purchase-return picklists.",
"type": "number",
"example": 5
},
"so_quantity_picked": {
"description": "Quantity already picked across all picklists for the underlying sales order line item. Returned only for `group_by=none`.",
"type": "number",
"example": 3
},
"pr_quantity_picked": {
"description": "Quantity already picked across all picklists for the underlying purchase return line item. Returned for purchase-return picklists.",
"type": "number",
"example": 2
},
"quantity_to_be_picked": {
"description": "Quantity of the item to be picked. Returned only for `group_by=none`.",
"type": "number",
"example": 5
},
"quantity_picked": {
"description": "Quantity already picked. Returned only for `group_by=none`.",
"type": "number",
"example": 3
},
"quantity_picked_remaining": {
"description": "Remaining quantity yet to be picked. Returned only for `group_by=none`.",
"type": "number",
"example": 2
},
"quantity_packed": {
"description": "Quantity that has been packed. Returned only for `group_by=none`.",
"type": "number",
"example": 3
},
"quantity_manually_fulfilled": {
"description": "Quantity that was manually fulfilled. Returned only for `group_by=none`.",
"type": "number",
"example": 0
},
"rate": {
"description": "Unit price/rate of the underlying line item. Returned only for `group_by=none`.",
"type": "number",
"example": 199.99
},
"status": {
"description": "Status of the line item. Returned only for `group_by=none` (for grouped picklists, status lives on each child entry inside `mapping_entity_details`).",
"type": "string",
"example": "inprogress"
},
"preferred_storage_id": {
"description": "ID of the preferred storage location for this item. Returned when storage tracking is enabled and `group_by` is `none` or `item`.",
"type": "string",
"example": "130426000000801001"
},
"preferred_storage_name": {
"description": "Name of the preferred storage location. Returned when storage tracking is enabled and `group_by` is `none` or `item`.",
"type": "string",
"example": "A-R1-B01"
},
"storages": {
"description": "Storage location breakdown used for picking. Returned only when storage tracking is enabled and `group_by=none`.",
"type": "array",
"items": {
"type": "object",
"properties": {
"storage_id": {
"type": "string",
"example": "130426000000801001"
},
"storage_name": {
"type": "string",
"example": "A-R1-B01"
},
"out_quantity": {
"type": "number",
"example": 5
}
}
}
},
"serial_numbers": {
"description": "Serial numbers picked. Returned only when serial-number tracking is enabled and `group_by=none`.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"SN-001",
"SN-002"
]
},
"batches": {
"description": "Batch details picked. Returned only when batch tracking is enabled and `group_by=none`.",
"type": "array",
"items": {
"type": "object",
"properties": {
"batch_number": {
"type": "string",
"example": "BATCH-001"
},
"out_quantity": {
"type": "number",
"example": 5
}
}
}
},
"track_serial_number": {
"description": "Whether serial-number tracking is enabled for this item. Returned only when serial-number tracking is enabled and `group_by=none`.",
"type": "boolean",
"example": false
},
"track_batch_number": {
"description": "Whether batch tracking is enabled for this item. Returned only when batch tracking is enabled and `group_by=none`.",
"type": "boolean",
"example": false
},
"track_serial_for_package": {
"description": "Whether serial numbers are required at the package level for this line item. Returned only for `group_by=none`.",
"type": "boolean",
"example": false
},
"track_batch_for_package": {
"description": "Whether batch numbers are required at the package level for this line item. Returned only for `group_by=none`.",
"type": "boolean",
"example": false
},
"item_custom_fields": {
"description": "Custom field values for the picked item. Returned only for `group_by=none`.",
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Lot"
},
"value": {
"type": "string",
"example": "L-2024-01"
}
}
}
},
"available_stock_for_picking": {
"description": "Stock currently available for picking. Returned only when `showAvailableStockForPicking` is enabled and `group_by` is `none` or `item`.",
"type": "number",
"example": 25
},
"advanced_tracking_missing_quantity": {
"description": "Quantity for which advanced tracking (serial / batch) details are missing. Returned only on create when tracking relaxation is enabled and `group_by=none`.",
"type": "number",
"example": 0
},
"upc": {
"description": "Universal Product Code of the item. Returned only when Zoho Inventory is enabled, the request is from a Zoho Books client, and `group_by=none`.",
"type": "string",
"example": "012345678905"
},
"ean": {
"description": "European Article Number of the item. Same return conditions as `upc`.",
"type": "string",
"example": "4006381333931"
},
"isbn": {
"description": "International Standard Book Number of the item. Same return conditions as `upc`.",
"type": "string",
"example": "978-3-16-148410-0"
}
}
},
"picklist-line-item-mapping": {
"description": "A child pick entry under a grouped picklist line item. Returned only for grouped picklists (`group_by=item` or `sales_order`). Each entry describes one underlying sales order line item being picked under the parent group, and carries the per-pick details (quantities, status, storages, tracking) that, in flat picklists, would live on the line item itself.",
"type": "object",
"properties": {
"mapping_line_item_id": {
"description": "Unique ID of this child mapping line item.",
"type": "string",
"example": "130426000000810031"
},
"mapping_entity_id": {
"description": "ID of the underlying child entity (sales order or item) this child entry belongs to.",
"type": "string",
"example": "130426000000700001"
},
"mapping_entity_name": {
"description": "Number / name of the underlying child entity (sales order number or item name).",
"type": "string",
"example": "SO-00001"
},
"mapping_entity_item_id": {
"description": "ID of the underlying sales order or purchase return line item being picked under this group.",
"type": "string",
"example": "130426000000700011"
},
"so_quantity_ordered": {
"description": "Total quantity ordered on the underlying sales order line item. Returned when the underlying entity is a sales order.",
"type": "number",
"example": 10
},
"quantity_ordered": {
"description": "Quantity ordered, normalized to the picking unit.",
"type": "number",
"example": 10
},
"so_quantity_picked": {
"description": "Quantity already picked across all picklists for the underlying sales order line item. Returned when the underlying entity is a sales order.",
"type": "number",
"example": 3
},
"item_id": {
"description": "ID of the item being picked. Returned when the parent group is grouped by sales order.",
"type": "string",
"example": "130426000000664040"
},
"name": {
"description": "Name of the item being picked.",
"type": "string",
"example": "Office Chair"
},
"sku": {
"description": "SKU of the item being picked.",
"type": "string",
"example": "CHAIR-001"
},
"is_storage_location_enabled": {
"description": "Whether storage location tracking is enabled for this item. Returned only when Zoho Inventory and storage tracking are enabled.",
"type": "boolean",
"example": true
},
"is_combo_product": {
"description": "Whether the item is a composite/combo product. Returned only when Zoho Inventory is enabled.",
"type": "boolean",
"example": false
},
"unit": {
"description": "Usage unit of the line item.",
"type": "string",
"example": "pcs"
},
"base_unit": {
"description": "Base unit configured on the item.",
"type": "string",
"example": "pcs"
},
"base_unit_id": {
"description": "ID of the base unit. Returned only when unit conversion is enabled.",
"type": "string",
"example": "130426000000900020"
},
"unit_conversion_id": {
"description": "ID of the unit conversion applied. Returned only when unit conversion is enabled.",
"type": "string",
"example": "130426000000900001"
},
"conversion_rate": {
"description": "Unit conversion rate. Returned only when unit conversion is enabled.",
"type": "number",
"example": 1
},
"quantity_decimal_place": {
"description": "Number of decimal places used for quantity values on this line item.",
"type": "integer",
"example": 2
},
"description": {
"description": "Description of the underlying line item.",
"type": "string",
"example": "Ergonomic mesh office chair."
},
"image_name": {
"description": "File name of the item image.",
"type": "string",
"example": "chair.png"
},
"image_type": {
"description": "File type of the item image.",
"type": "string",
"example": "png"
},
"image_document_id": {
"description": "Document ID of the item image.",
"type": "string",
"example": "130426000000910001"
},
"quantity_to_be_picked": {
"description": "Quantity to be picked for this child entry.",
"type": "number",
"example": 5
},
"quantity_picked": {
"description": "Quantity already picked for this child entry.",
"type": "number",
"example": 3
},
"quantity_picked_remaining": {
"description": "Remaining quantity yet to be picked for this child entry.",
"type": "number",
"example": 2
},
"quantity_packed": {
"description": "Quantity already packed for this child entry.",
"type": "number",
"example": 0
},
"quantity_manually_fulfilled": {
"description": "Quantity that was manually fulfilled for this child entry.",
"type": "number",
"example": 0
},
"rate": {
"description": "Unit price/rate of the underlying line item.",
"type": "number",
"example": 199.99
},
"status": {
"description": "Status of this child mapping entry.",
"type": "string",
"pattern": "(yet_to_start|in_progress|on_hold|completed)",
"example": "in_progress"
},
"preferred_storage_id": {
"description": "ID of the preferred storage location for this child entry.",
"type": "string",
"example": "130426000000801001"
},
"preferred_storage_name": {
"description": "Name of the preferred storage location.",
"type": "string",
"example": "A-R1-B01"
},
"storages": {
"description": "Storage location breakdown used for picking this child entry.",
"type": "array",
"items": {
"type": "object",
"properties": {
"storage_id": {
"type": "string",
"example": "130426000000801001"
},
"storage_name": {
"type": "string",
"example": "A-R1-B01"
},
"out_quantity": {
"type": "number",
"example": 5
}
}
}
},
"serial_numbers": {
"description": "Serial numbers picked for this child entry.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"SN-001",
"SN-002"
]
},
"batches": {
"description": "Batch details picked for this child entry.",
"type": "array",
"items": {
"type": "object",
"properties": {
"batch_number": {
"type": "string",
"example": "BATCH-001"
},
"out_quantity": {
"type": "number",
"example": 5
},
"storages": {
"description": "Storage location breakdown used for picking this child entry.",
"type": "array",
"items": {
"type": "object",
"properties": {
"storage_id": {
"type": "string",
"example": "130426000000801001"
},
"storage_name": {
"type": "string",
"example": "A-R1-B01"
},
"out_quantity": {
"type": "number",
"example": 5
}
}
}
}
}
}
},
"item_custom_fields": {
"description": "Custom field values for the picked item in this child entry.",
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Lot"
},
"value": {
"type": "string",
"example": "L-2024-01"
}
}
}
},
"track_serial_number": {
"description": "Whether serial-number tracking is enabled for this item. Returned only when serial-number tracking is enabled in the org.",
"type": "boolean",
"example": false
},
"track_batch_number": {
"description": "Whether batch tracking is enabled for this item. Returned only when batch tracking is enabled in the org.",
"type": "boolean",
"example": false
},
"track_serial_for_package": {
"description": "Whether serial numbers are required at the package level for this line item.",
"type": "boolean",
"example": false
},
"track_batch_for_package": {
"description": "Whether batch numbers are required at the package level for this line item.",
"type": "boolean",
"example": false
},
"available_stock_for_picking": {
"description": "Stock currently available for picking. Returned only when `showAvailableStockForPicking` is enabled.",
"type": "number",
"example": 25
},
"advanced_tracking_missing_quantity": {
"description": "Quantity for which advanced tracking (serial / batch) details are missing. Returned only on create when tracking relaxation is enabled in the org.",
"type": "number",
"example": 0
},
"upc": {
"description": "Universal Product Code of the item. Returned only when Zoho Inventory is enabled and the request is from a Zoho Books client.",
"type": "string",
"example": "012345678905"
},
"ean": {
"description": "European Article Number of the item. Returned only when Zoho Inventory is enabled and the request is from a Zoho Books client.",
"type": "string",
"example": "4006381333931"
},
"isbn": {
"description": "International Standard Book Number of the item. Returned only when Zoho Inventory is enabled and the request is from a Zoho Books client.",
"type": "string",
"example": "978-3-16-148410-0"
}
}
},
"picklist-line-item-mapping-request": {
"description": "A child pick entry under a grouped picklist line item. Used only when `group_by` is `item` or `sales_order`. Provide one entry inside `mapping_entity_details` for every underlying sales order line item to be picked under the parent group.",
"type": "object",
"properties": {
"mapping_line_item_id": {
"description": "ID of an existing child entry. Pass on update to identify the row being modified; omit when adding a new one.",
"type": "string",
"example": "130426000000810031"
},
"mapping_entity_item_id": {
"description": "ID of the underlying sales order line item to be picked. Required when adding a new child entry.",
"type": "string",
"example": "130426000000700011"
},
"quantity_to_be_picked": {
"description": "Quantity to be picked for this child entry.",
"type": "number",
"example": 5
},
"quantity_picked": {
"description": "Quantity already picked for this child entry.",
"type": "number",
"example": 3
},
"status": {
"description": "Status of this child mapping entry.",
"type": "string",
"enum": [
"yettostart",
"inprogress",
"onhold",
"completed"
],
"example": "inprogress"
},
"preferred_storage_id": {
"description": "ID of the preferred storage location for this child entry.",
"type": "string",
"example": "130426000000801001"
},
"storages": {
"description": "Storage location assignments for this child entry. Maximum 100.",
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"storage_id": {
"description": "ID of the storage location.",
"type": "string",
"example": "130426000000801001"
},
"out_quantity": {
"description": "Quantity assigned to this storage location.",
"type": "number",
"example": 5
}
}
}
},
"serial_numbers": {
"description": "Serial numbers picked for this child entry. Maximum 10000.",
"type": "array",
"maxItems": 10000,
"items": {
"type": "string"
},
"example": [
"SN-001",
"SN-002"
]
},
"batches": {
"description": "Batch details picked for this child entry. Maximum 100.",
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"batch_id": {
"description": "Batch identifier.",
"type": "string",
"example": "130426000000810031"
},
"out_quantity": {
"description": "Quantity in this batch.",
"type": "number",
"example": 5
},
"storages": {
"description": "Storage location breakdown used for picking this child entry.",
"type": "array",
"items": {
"type": "object",
"properties": {
"storage_id": {
"description": "ID of the storage location.",
"type": "string",
"example": "130426000000801001"
},
"out_quantity": {
"description": "Quantity assigned to this storage location.",
"type": "number",
"example": 5
}
}
}
}
}
}
},
"item_custom_fields": {
"description": "Custom field values for the picked item in this child entry. Maximum 1000.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"properties": {
"label": {
"description": "Label of the custom field.",
"type": "string",
"example": "Lot"
},
"value": {
"description": "Value for the custom field.",
"type": "string",
"example": "L-2024-01"
}
}
}
}
}
},
"picklist-line-item-request": {
"description": "A line item in a picklist create/update request. Two mutually-exclusive shapes, controlled by `group_by`:\n\n- **Flat (`group_by=none`)** - populate pick fields (`quantity_to_be_picked`, `storages`, `serial_numbers`, `batches`, `status`, `preferred_storage_id`, `item_custom_fields`, the `*_line_item_id` references) directly on this object. Do **not** send `mapping_entity_details`.\n- **Grouped (`group_by=item` or `sales_order`)** - only `line_item_id` (on update), `assignee_id` and `mapping_entity_details` are valid here. All actual pick details belong to each child entry inside `mapping_entity_details`.\n",
"type": "object",
"properties": {
"line
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/json-schema/picklists.json