Add Material to Pick List

Adds a material line item to a pick list. Returns `201 Created`. ## Identifying the material Provide the material using one of the following combinations. All invalid combinations and resolution failures return `400`. - **`materialDetailsId`** (most precise) — adds that exact material details record. If `materialId` and/or `materialVariationId` are also sent, they must match the record or the request is rejected with `400`. - **`materialId` only** — resolves the material at the pick list's source location (`fromLocation`). Succeeds only when the material has a single variation stocked there. Returns `400` if the material is not stocked at the source location, or if it has more than one variation stocked there (add `materialVariationId` to disambiguate, or pass `materialDetailsId`). - **`materialId` + `materialVariationId`** — resolves the specified variation at the source location. Returns `400` if that variation is not stocked there. `materialVariationId` must always be accompanied by `materialId`; sent on its own it returns `400`. Sending neither `materialDetailsId` nor `materialId` also returns `400`. ## When `materialVariationId` is required A catalog material can have several variations (e.g. sizes or colors) stocked at the same location, each its own material details record. `materialId` alone cannot pick between them, so it returns `400` until you either add `materialVariationId` or pass the specific `materialDetailsId`. Materials with a single variation at the source location resolve from `materialId` alone. ## Finding the materialDetailsId If you prefer to add by `materialDetailsId`, retrieve it from `GET /locations/{id}/materials` — each row's `materialDetailsId` is the value to send here. Filter that endpoint with `materialIds` to find the record(s) for a known material at the source location. Requires scope: `pick_lists:write`

Authentication

API_KEYstring
API Key authentication via header

Path parameters

idUUIDRequired
Pick list ID.

Request

This endpoint expects an object.
quantitydoubleRequired
Quantity to pick. Required. Must be greater than zero.
materialDetailsIdUUIDOptional

ID of the specific material details record (a material’s presence at a location) to add. The most precise identifier. Retrieve it from GET /locations/{id}/materials (the materialDetailsId field). If provided, materialId/materialVariationId are optional and, when present, are validated against this record. Required unless materialId is provided.

materialIdUUIDOptional

ID of the catalog material to add. The material is resolved to a material details record at the pick list’s source location (fromLocation). Required unless materialDetailsId is provided.

materialVariationIdUUIDOptional

ID of the material variation. Must be provided together with materialId (it is rejected on its own). Use it to disambiguate when the material has more than one variation stocked at the source location.

notestringOptional
Optional note for this line item.

Response

This endpoint returns an object.
idUUID
Unique identifier for this pick list material record.
quantitydouble
Quantity to be picked.
materialobject
Reference to the parent material.
variationobject
Reference to the material variation, if applicable.
notestring
Optional note for this material line item.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error