> ## Documentation Index > Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt > Use this file to discover all available pages before exploring further. # Create picking batch > Groups ready-to-pick shipments in a warehouse into a new picking batch. The batch is built from either a batch preset (`batch_preset_id`) or a picking class (`picking_class_id`), and is sized by an asset type (`asset_type_id`) or an explicit `max_shipments`. The remaining properties filter which shipments are eligible and control how the batch is picked. When a user token is used, the user must have permission to process orders and must have access to the warehouse. A `422` response is returned when no batch could be created, for example when no eligible shipments are available or when there are not enough shipments to fill the batch and partial batches are not allowed. When some shipments could not be picked, the error `details` explain why. ## OpenAPI ````yaml POST /v1/operations/picking-batches openapi: 3.0.3 info: title: ShipStream version: '1.0' license: name: Commercial (Copyright 2025 - All Rights Reserved) url: https://shipstream.io contact: name: ShipStream Support email: help@shipstream.io termsOfService: https://shipstream.io/legal/api-terms/ servers: - url: https://{base_url_domain}/api/global description: Direct API Url variables: base_url_domain: default: example.shipstream.app description: >- The fully qualified domain name for your ShipStream WMS instance. This is either a custom domain, or a subdomain of shipstream.app, and will be the same as the domain name for the page which you use to login to ShipStream WMS. security: - ShipStream_bearerAuth: [] tags: - name: Warehouses x-displayName: Warehouses - name: Products x-displayName: Products - name: ProductProfiles x-displayName: ProductProfiles - name: HandlingClasses x-displayName: HandlingClasses - name: Locations x-displayName: Locations - name: LocationOccupancies x-displayName: LocationOccupancies - name: LocationTags x-displayName: LocationTags - name: SlotTypes x-displayName: SlotTypes - name: Levels x-displayName: Levels - name: HoldReasons x-displayName: HoldReasons - name: Holds x-displayName: Holds - name: Replenishment x-displayName: Replenishment - name: LocationProfiles x-displayName: LocationProfiles - name: SlottingRules x-displayName: SlottingRules - name: PickingBatches x-displayName: PickingBatches - name: Deliveries description: Every thing about a Delivery Receiving x-displayName: Deliveries - name: Shipments x-displayName: Shipments - name: Orders x-displayName: Orders - name: Retailers x-displayName: Retailers - name: Users x-displayName: Users - name: User Roles x-displayName: User Roles - name: Merchants x-displayName: Merchants - name: Healthcheck x-displayName: Healthcheck paths: /v1/operations/picking-batches: post: tags: - PickingBatches summary: Create picking batch description: >- Groups ready-to-pick shipments in a warehouse into a new picking batch. The batch is built from either a batch preset (`batch_preset_id`) or a picking class (`picking_class_id`), and is sized by an asset type (`asset_type_id`) or an explicit `max_shipments`. The remaining properties filter which shipments are eligible and control how the batch is picked. When a user token is used, the user must have permission to process orders and must have access to the warehouse. A `422` response is returned when no batch could be created, for example when no eligible shipments are available or when there are not enough shipments to fill the batch and partial batches are not allowed. When some shipments could not be picked, the error `details` explain why. operationId: createPickingBatch requestBody: required: true content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/Operations_API_v1_PickingBatchCriteria' - type: object required: - warehouse_id example: warehouse_id: 1 picking_class_id: 2 asset_type_id: 5 target_ship_date: on_or_before_current merchant_ids: - 2 print_packing_instructions: false responses: '201': description: The picking batch was created. content: application/json: schema: type: object properties: resource: $ref: '#/components/schemas/Operations_API_v1_PickingBatch' meta: type: object description: Response metadata. properties: processing_time: type: number description: >- Total time in which request is processed and response is sent back. format: float required: - resource additionalProperties: false '400': $ref: '#/components/responses/Operations_API_v1_400-bad-request' '403': description: >- The authenticated user is not permitted to perform the request; or the admin session cookie's sign-in must still enter its emailed login code (login_verification_pending, with verify_url) or needs a stronger sign-in (login_strength_required). A pending client user, whose code is emailed only to a sign-in on the client portal, is signed out and verify_url is the client portal's login page. content: application/json: schema: oneOf: - ee0bec75-4b93-456a-a5c2-128e7703c793 - $ref: >- #/components/schemas/Operations_API_v1_LoginVerificationError '404': $ref: '#/components/responses/Operations_API_v1_404-not-found' '422': $ref: '#/components/responses/Operations_API_v1_422-unprocessable' '500': $ref: '#/components/responses/Operations_API_v1_500-internal-server-error' security: - Operations_API_v1_bearerAuth: [] components: schemas: Operations_API_v1_PickingBatchCriteria: title: PickingBatchCriteria type: object description: >- Selects which ready-to-pick shipments in a warehouse are grouped into a picking batch and how the batch is picked. A batch is built from either a batch preset or a picking class, and is sized by either an asset type or an explicit maximum number of shipments. All filters are optional; omitted filters do not restrict the selection. properties: warehouse_id: type: integer format: int32 minimum: 1 example: 1 description: >- The warehouse whose shipments are batched. The authenticated user must have access to it. shipment_type: type: string nullable: true enum: - parcel - freight - null example: parcel description: >- Only batch shipments of this type. Omit or `null` to batch shipments of any type. batch_preset_id: type: integer format: int32 minimum: 1 example: 3 description: >- Build the batch from this batch preset. The preset supplies the picking classes, sizing and defaults for `location_accessibility` and `print_packing_instructions`. Either `batch_preset_id` or `picking_class_id` is required. picking_class_id: type: integer format: int32 minimum: 1 example: 2 description: >- Build the batch from shipments in this picking class. Either `batch_preset_id` or `picking_class_id` is required. asset_type_id: type: integer format: int32 minimum: 1 example: 5 description: >- Size the batch for this asset type (e.g. a cart). The maximum number of shipments is derived from the asset type unless `max_shipments` is also given. Either `asset_type_id` or `max_shipments` is required unless the batch preset sizes the batch. max_shipments: type: integer format: int32 minimum: 1 example: 24 description: The maximum number of shipments in the batch. workflow: type: string enum: - paper_in_bin - paperless example: paper_in_bin description: >- The picking workflow. `paper_in_bin` prints packing slips placed into bins; `paperless` prints no packing slips. Omit to use the batch preset's default workflow, or the system default when there is no preset. batch_tag: type: string nullable: true maxLength: 255 example: PRIORITY description: >- Only batch shipments with this batch tag. An empty string selects shipments without a batch tag. Omit or `null` to ignore batch tags. exclude_batch_tag: type: boolean default: false example: false description: >- When `true`, `batch_tag` excludes matching shipments instead of selecting them. shipping_methods: type: array maxItems: 1000 items: type: string description: A shipping method code in the form `{carrier}_{method}`. example: - ups_03 description: Only batch shipments using one of these shipping methods. exclude_shipping_methods: type: boolean default: false example: false description: >- When `true`, `shipping_methods` excludes matching shipments instead of selecting them. merchant_ids: type: array maxItems: 1000 items: type: integer format: int32 description: A merchant `id`. example: - 2 description: Only batch shipments belonging to one of these merchants. exclude_merchants: type: boolean default: false example: false description: >- When `true`, `merchant_ids` excludes matching shipments instead of selecting them. service_levels: type: array maxItems: 1000 items: type: string description: A service level code. example: - ground description: Only batch shipments with one of these service levels. exclude_service_levels: type: boolean default: false example: false description: >- When `true`, `service_levels` excludes matching shipments instead of selecting them. target_ship_date: type: string enum: - on_or_before_current - before_current - current_only - after_current - any example: on_or_before_current description: >- Selects shipments by target ship date relative to the warehouse's current target ship date. Omit to select shipments due on or before the current target ship date. location_accessibility: type: string enum: - accessible_only - sweep - any example: accessible_only description: >- Which inventory locations may be picked from. `accessible_only` (Strict) follows the asset policies, `sweep` prefers accessible locations but may pick from others, and `any` (Disregard) ignores accessibility. Omit to use the batch preset's default, or `accessible_only` when there is no preset. print_packing_instructions: type: boolean example: false description: >- Whether to print packing instructions for the batch. Omit to use the batch preset's setting, or `false` when there is no preset. allow_partial: type: boolean example: false description: >- Whether to create the batch when there are not enough shipments to fill it. Omit to use the warehouse's default. Ignored when the warehouse is configured to always or never allow partial batches. additionalProperties: false Operations_API_v1_PickingBatch: title: PickingBatch type: object description: A picking batch groups shipments so they can be picked together. properties: type: type: string enum: - PickingBatch description: The resource type identifier. id: type: integer format: int32 example: 1024 description: The picking batch number. warehouse_id: type: integer format: int32 example: 1 description: The warehouse the batch belongs to. shipment_count: type: integer format: int32 example: 24 description: The number of shipments in the batch. workflow: type: string nullable: true enum: - paper_in_bin - paperless - null example: paper_in_bin description: The picking workflow used by the batch. batch_preset_id: type: integer format: int32 nullable: true example: 3 description: >- The batch preset the batch was built from, or `null` when built from a picking class. picking_class_id: type: integer format: int32 nullable: true example: 2 description: >- The picking class the batch was built from, or `null` when built from a batch preset. asset_type_id: type: integer format: int32 nullable: true example: 5 description: >- The asset type the batch was sized for, or `null` when sized by `max_shipments`. max_shipments: type: integer format: int32 example: 24 description: The maximum number of shipments the batch could hold. location_accessibility: type: string enum: - accessible_only - sweep - any example: accessible_only description: Which inventory locations the batch may be picked from. print_packing_instructions: type: boolean example: false description: Whether packing instructions are printed for the batch. allow_partial: type: boolean example: false description: >- Whether the batch was allowed to be created with fewer shipments than it could hold. required: - type - id - warehouse_id - shipment_count - workflow - batch_preset_id - picking_class_id - asset_type_id - max_shipments - location_accessibility - print_packing_instructions - allow_partial additionalProperties: false Operations_API_v1_LoginVerificationError: type: object description: >- Refusal of a sign-in that has not met its login requirement: it must still enter its emailed login code, or it needs a stronger sign-in. additionalProperties: false required: - error - message properties: error: type: string description: Error code. enum: - login_verification_pending - login_strength_required message: type: string description: Human-readable message. verify_url: type: string description: >- Present for login_verification_pending: the code page, or, for a client user, whose code is emailed only to a sign-in on the client portal, the client portal's login page; that session is signed out. meta: type: object description: Response metadata; present on handler responses only. additionalProperties: false properties: processing_time: type: number description: Server processing time in seconds. responses: Operations_API_v1_400-bad-request: description: >- The request was invalid. The client must change the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - parser - parameters - openapi message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: parameters message: The supplied parameters are invalid. Operations_API_v1_404-not-found: description: >- The requested resource was not found. It may have been deleted, it may have never existed, or you may not have permission to view it. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - not_found message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: not_found message: The server could not find the requested resource. Operations_API_v1_422-unprocessable: description: >- There was an error processing the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - application - unable_to_process message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: unable_to_process message: There was an error processing the request. Operations_API_v1_500-internal-server-error: description: >- Internal Server Error - Something wrong happened at server side. Contact server administrator for more details. securitySchemes: ShipStream_bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Generate a JWT access token through a Custom Global Integration and provide it with each request in the `Authorization` header prefixed with "Bearer" and then a single space. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.