Zoho Inventory picklists API

openapi: 3.0.0
info:
  title: batches picklists 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: picklists
  description: Picklists Module
paths:
  /picklists:
    x-mcp-group:
    - Picklists
    get:
      tags:
      - picklists
      operationId: list_picklists
      summary: List Picklists
      description: Retrieve the list of all picklists in the organization.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: sort_column
        in: query
        description: Column by which the list is sorted.
        schema:
          type: string
          enum:
          - salesorder_number
          - picklist_number
          - date
          - created_time
          - last_modified_time
          - purchase_return_number
        example: date
      - name: sort_order
        in: query
        description: Sort order. `A` for ascending, `D` for descending.
        schema:
          type: string
          enum:
          - A
          - D
        example: D
      - name: search_text
        in: query
        description: Search text to filter picklists by name or number.
        schema:
          type: string
        example: Pick-00001
      - name: filter_by
        in: query
        description: 'Filter picklists by status. Example: `Status.All`, `Status.YetToStart`, `Status.InProgress`, `Status.OnHold`, `Status.Completed`, or `MissingAdvancedTrackingDetails`.'
        schema:
          type: string
        example: Status.InProgress
      - name: salesorder_number
        in: query
        description: Filter by sales order number.
        schema:
          type: string
        example: SO-00001
      - name: salesorder_number_startswith
        in: query
        description: Filter picklists where the associated sales order number starts with the given value.
        schema:
          type: string
        example: SO-0
      - name: salesorder_number_contains
        in: query
        description: Filter picklists where the associated sales order number contains the given value.
        schema:
          type: string
        example: '0001'
      - name: purchase_return_number
        in: query
        description: Filter by purchase return number.
        schema:
          type: string
        example: PR-00001
      - name: purchase_return_number_startswith
        in: query
        description: Filter picklists where the associated purchase return number starts with the given value.
        schema:
          type: string
        example: PR-0
      - name: purchase_return_number_contains
        in: query
        description: Filter picklists where the associated purchase return number contains the given value.
        schema:
          type: string
        example: '0001'
      - name: picklist_number
        in: query
        description: Filter by picklist number.
        schema:
          type: string
        example: Pick-00001
      - name: picklist_number_startswith
        in: query
        description: Filter picklists where the picklist number starts with the given value.
        schema:
          type: string
        example: Pick-0
      - name: picklist_number_contains
        in: query
        description: Filter picklists where the picklist number contains the given value.
        schema:
          type: string
        example: '0001'
      - name: item_id
        in: query
        description: Filter picklists that contain the specified item.
        schema:
          type: string
        example: '130426000000664040'
      - name: location_id
        in: query
        description: Filter picklists by location.
        schema:
          type: string
        example: '130426000000664030'
      - name: customer_id
        in: query
        description: Filter picklists by customer.
        schema:
          type: string
        example: '130426000000664050'
      - name: assignee_id
        in: query
        description: Filter picklists by the assigned user.
        schema:
          type: string
        example: '130426000000664060'
      - name: date
        in: query
        description: Filter picklists by a specific date (yyyy-mm-dd).
        schema:
          type: string
          format: date
        example: '2024-01-15'
      - name: date_start
        in: query
        description: Filter picklists from this start date (yyyy-mm-dd).
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: date_end
        in: query
        description: Filter picklists up to this end date (yyyy-mm-dd).
        schema:
          type: string
          format: date
        example: '2024-01-31'
      - name: status
        in: query
        description: Filter picklists by status.
        schema:
          type: string
          enum:
          - yettostart
          - inprogress
          - onhold
          - completed
        example: inprogress
      - name: customview_id
        in: query
        description: ID of a custom view to apply.
        schema:
          type: string
        example: '130426000000664070'
      - name: page
        in: query
        description: Page number for pagination.
        schema:
          type: integer
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Number of records per page.
        schema:
          type: integer
          default: 10
        example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-picklists-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.READ
    post:
      tags:
      - picklists
      operationId: create_picklist
      summary: Create a Picklist
      description: Create a new picklist for picking items.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: ignore_auto_number_generation
        in: query
        description: Set to `true` to use a custom picklist number instead of the auto-generated one.
        schema:
          type: boolean
        example: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-picklist-request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/picklist-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.CREATE
    delete:
      tags:
      - picklists
      operationId: bulk_delete_picklists
      summary: Bulk Delete Picklists
      description: Delete multiple picklists at once.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: picklist_ids
        in: query
        description: Comma-separated list of picklist IDs to delete. Maximum 200 IDs.
        required: true
        schema:
          type: string
        example: 130426000000810001,130426000000810002
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.DELETE
  /picklists/{picklist_id}:
    x-mcp-group:
    - Picklists
    parameters:
    - name: picklist_id
      in: path
      required: true
      description: Unique identifier of the picklist.
      schema:
        type: string
      example: '130426000000810001'
    get:
      tags:
      - picklists
      operationId: get_picklist
      summary: Get a Picklist
      description: Retrieve the details of an existing picklist.
      parameters:
      - name: print
        in: query
        description: Set to `true` to return print-friendly content.
        schema:
          type: boolean
        example: false
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/picklist-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.READ
    put:
      tags:
      - picklists
      operationId: update_picklist
      summary: Update a Picklist
      description: Update the details of an existing picklist.
      parameters:
      - name: ignore_auto_number_generation
        in: query
        description: Set to `true` to use a custom picklist number instead of the auto-generated one.
        schema:
          type: boolean
        example: false
      - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-a-picklist-request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/picklist-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.UPDATE
    delete:
      tags:
      - picklists
      operationId: delete_picklist
      summary: Delete a Picklist
      description: Delete an existing picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.DELETE
  /picklists/{picklist_id}/setstatus:
    x-mcp-group:
    - Picklists
    parameters:
    - name: picklist_id
      in: path
      required: true
      description: Unique identifier of the picklist.
      schema:
        type: string
      example: '130426000000810001'
    post:
      tags:
      - picklists
      operationId: set_picklist_status
      summary: Set Status of a Picklist
      description: Update the status of a specific picklist.
      parameters:
      - name: status
        in: query
        required: true
        description: The new status to set for the picklist.
        schema:
          type: string
          enum:
          - yettostart
          - inprogress
          - onhold
          - completed
        example: completed
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.UPDATE
  /picklists/setstatus:
    x-mcp-group:
    - Picklists
    post:
      tags:
      - picklists
      operationId: bulk_set_picklist_status
      summary: Bulk Set Status of Picklists
      description: Update the status of multiple picklists at once.
      parameters:
      - name: picklist_ids
        in: query
        required: true
        description: Comma-separated list of picklist IDs. Maximum 25 IDs.
        schema:
          type: string
        example: 130426000000810001,130426000000810002
      - name: picklist_item_ids
        in: query
        description: Comma-separated list of picklist item IDs to update. Maximum 50 IDs.
        schema:
          type: string
        example: 130426000000810011,130426000000810012
      - name: status
        in: query
        required: true
        description: The new status to assign to the specified picklists.
        schema:
          type: string
          enum:
          - yettostart
          - inprogress
          - onhold
          - completed
        example: completed
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.UPDATE
  /picklists/{picklist_id}/comments:
    x-mcp-group:
    - Picklists
    parameters:
    - name: picklist_id
      in: path
      required: true
      description: Unique identifier of the picklist.
      schema:
        type: string
      example: '130426000000810001'
    post:
      tags:
      - picklists
      operationId: add_comment_to_picklist
      summary: Add a Comment to a Picklist
      description: Add a comment or note to an existing picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/add-comment-request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/comment-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.UPDATE
  /picklists/{picklist_id}/comments/{comment_id}:
    x-mcp-group:
    - Picklists
    parameters:
    - name: picklist_id
      in: path
      required: true
      description: Unique identifier of the picklist.
      schema:
        type: string
      example: '130426000000810001'
    - name: comment_id
      in: path
      required: true
      description: Unique identifier of the comment.
      schema:
        type: string
      example: '130426000000810021'
    delete:
      tags:
      - picklists
      operationId: delete_picklist_comment
      summary: Delete a Comment on a Picklist
      description: Delete a comment from an existing picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.DELETE
  /picklists/{picklist_id}/advancedtrackingdetails:
    x-mcp-group:
    - Picklists
    parameters:
    - name: picklist_id
      in: path
      required: true
      description: Unique identifier of the picklist.
      schema:
        type: string
      example: '130426000000810001'
    get:
      tags:
      - picklists
      operationId: get_picklist_advanced_tracking_details
      summary: Get Advanced Tracking Details for a Picklist
      description: Retrieve the serial number and batch tracking details for a picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/advanced-tracking-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.READ
    put:
      tags:
      - picklists
      operationId: update_picklist_advanced_tracking_details
      summary: Update Advanced Tracking Details for a Picklist
      description: Update serial number and batch tracking details for items in a picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-advanced-tracking-request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.picklists.UPDATE
  /picklists/searchsolineitems:
    x-mcp-group:
    - Picklists
    get:
      tags:
      - picklists
      operationId: search_so_line_items_for_picklist
      summary: Search Sales Order Line Items
      description: Search for sales order line items that can be added to a picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: customer_ids_in
        in: query
        description: Comma-separated list of customer IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000664050,130426000000664051
      - name: salesorder_ids_in
        in: query
        description: Comma-separated list of sales order IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000700001,130426000000700002
      - name: item_ids_in
        in: query
        description: Comma-separated list of item IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000664040,130426000000664041
      - name: location_id
        in: query
        description: Filter by location.
        schema:
          type: string
        example: '130426000000664030'
      - name: line_item_location_id
        in: query
        description: Filter by the location associated with the line item.
        schema:
          type: string
        example: '130426000000664031'
      - name: sort_column
        in: query
        description: Column by which the results are sorted.
        schema:
          type: string
          enum:
          - salesorder_number
          - name
          - sku
        example: salesorder_number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search-so-line-items-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesorders.READ
  /picklists/searchso:
    x-mcp-group:
    - Picklists
    get:
      tags:
      - picklists
      operationId: search_sales_orders_for_picklist
      summary: Search Sales Orders
      description: Search for sales orders that can be used when creating a picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: customer_ids_in
        in: query
        description: Comma-separated list of customer IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000664050,130426000000664051
      - name: location_id
        in: query
        description: Filter by location.
        schema:
          type: string
        example: '130426000000664030'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search-sales-orders-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesorders.READ
  /picklists/searchprlineitems:
    x-mcp-group:
    - Picklists
    get:
      tags:
      - picklists
      operationId: search_pr_line_items_for_picklist
      summary: Search Purchase Return Line Items
      description: Search for purchase return line items that can be added to a picklist.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - name: vendor_ids_in
        in: query
        description: Comma-separated list of vendor IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000664055,130426000000664056
      - name: purchasereturn_ids_in
        in: query
        description: Comma-separated list of purchase return IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000720001,130426000000720002
      - name: item_ids_in
        in: query
        description: Comma-separated list of item IDs to filter by. Maximum 50.
        schema:
          type: string
        example: 130426000000664040,130426000000664041
      - name: location_id
        in: query
        description: Filter by location.
        schema:
          type: string
        example: '130426000000664030'
      - name: line_item_location_id
        in: query
        description: Filter by the location associated with the line item.
        schema:
          type: string
        example: '130426000000664031'
      - name: sort_column
        in: query
        description: Column by which the results are sorted.
        schema:
          type: string
          enum:
          - purchasereturn_number
          - name
          - sku
        example: purchasereturn_number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search-pr-line-items-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.purchasereturns.READ
components:
  schemas:
    add-comment-request:
      description: Request body for adding a comment to a picklist.
      type: object
      properties:
        description:
          description: Text content of the comment.
          type: string
          example: Items checked and ready for dispatch.
    picklist-object:
      description: A picklist record.
      type: object
      properties:
        picklist_id:
          $ref: '#/components/schemas/picklist_id'
        picklist_number:
          $ref: '#/components/schemas/picklist_number'
        date:
          description: Date of the picklist.
          type: string
          format: date
          readOnly: true
          example: '2024-01-15'
        notes:
          description: Internal notes for the picklist.
          type: string
          readOnly: true
          example: Fragile items - handle with care.
        assignee_id:
          description: ID of the user assigned to the picklist.
          type: string
          readOnly: true
          example: '130426000000664060'
        assignee_name:
          description: Name of the user assigned to the picklist.
          type: string
          readOnly: true
          example: John Doe
        location_id:
          description: ID of the location.
          type: string
          readOnly: true
          example: '130426000000664030'
        location_name:
          description: Name of the location.
          type: string
          readOnly: true
          example: New York
        status:
          description: Current status of the picklist.
          type: string
          readOnly: true
          example: inprogress
        created_time:
          description: Timestamp when the picklist was created.
          type: string
          readOnly: true
          example: '2024-01-15T10:30:00+05:30'
        last_modified_time:
          description: Timestamp when the picklist was last modified.
          type: string
          readOnly: true
          example: '2024-01-15T11:00:00+05:30'
        salesorder_numbers:
          description: List of sales order numbers associated with this picklist.
          type: array
          readOnly: true
          items:
            type: string
          example:
          - SO-00001
          - SO-00002
        purchase_return_numbers:
          description: List of purchase return numbers associated with this picklist.
          type: array
          readOnly: true
          items:
            type: string
          example:
          - PR-00001
        customer_names:
          description: List of customer names associated with this picklist.
          type: array
          readOnly: true
          items:
            type: string
          example:
          - Acme Corp
    picklist-line-item-request:
      description: 'A line item in a picklist create/update request. Two mutually-exclusive shapes, controlled by `group_by`:


        - **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`.

        - **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`.

        '
      type: object
      properties:
        line_item_id:
          description: ID of an existing picklist line item. Pass on update to identify the row being modified; omit on create.
          type: string
          example: '130426000000810011'
        salesorder_id:
          description: ID of the associated sales order. Flat mode or group by sales order.
          type: string
          example: '130426000000700001'
        parent_entity_id:
          description: ID of the parent entity (sales order or purchase return). Flat mode only.
          type: string
          example: '130426000000700001'
        so_line_item_id:
          description: ID of the underlying sales order line item. Flat mode only.
          type: string
          example: '130426000000700011'
        pr_line_item_id:
          description: ID of the underlying purchase return line item. Flat mode only.
          type: string
          example: '130426000000720011'
        parent_line_item_id:
          description: ID of the parent line item on the source entity. Flat mode only.
          type: string
          example: '130426000000700011'
        quantity_to_be_picked:
          description: Quantity of the item to be picked. Flat mode only.
          type: number
          example: 5
        quantity_picked:
          description: Quantity already picked. Flat mode only.
          type: number
          example: 3
        status:
          description: Status of the line item. Flat mode only.
          type: string
          enum:
          - yettostart
          - inprogress
          - onhold
          - completed
          example: inprogress
        preferred_storage_id:
          description: ID of the preferred storage location for this item. Flat mode or group by item.
          type: string
          example: '130426000000801001'
        storages:
          description: Storage location assignments. Flat mode only. 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 assigned to this line item. Flat mode only. Maximum 10000.
          type: array
          maxItems: 10000
          items:
            type: string
          example:
          - SN-001
          - SN-002
        batches:
          description: Batch details for this line item. Flat mode only. 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 for this batch.
                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 item. Flat mode only. Maximum 1000.
          type: array
          maxItems: 1000
          items:
            type: object
            properties:
              label:
                description: Label of the custom field.
                type: string
                example: Zone
              value:
                description: Value for the custom field.
                type: string
                example: Zone A
        assignee_id:
          description: ID of the user assigned to this line item. For grouped picklists, assigns the picker to the entire group. This is not used for non-grouped picklists.
          type: string
          example: '130426000000664060'
        mapping_entity_details:
          description: Child pick entries grouped under this parent line item. **Required for grouped picklists** (`group_by=item` or `sales_order`) and must contain at least one entry. Must be omitted for `group_by=none`. Maximum 1000 entries.
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/picklist-line-item-mapping-request'
    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.
                      ty

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-picklists-api-openapi.yml