API ReferenceJobs

Transfer Material to Job

Transfers stock of a material from a warehouse or truck into a job — the same operation as a transfer in the Ply app. The quantity is deducted from the source location after an availability check, inventory layers are consumed to lock the job's material cost, and a transfer activity is recorded with the given reason. When the job is linked to a connected field-service integration, its line items are pushed there as well. Transferring a material that is already on the job from the same source increases the existing row's quantity. Serialized units become one quantity-1 row per serial number, so a single transfer can return multiple rows. When `serialNumbers` is supplied its length must equal `quantity`; a mismatch returns `400`. A concurrent transfer into the same job returns `409`; retry once the in-flight transfer completes. Requires scope: `jobs:write`

Authentication

API_KEYstring
API Key authentication via header

Path parameters

idUUIDRequired
Job ID.

Request

This endpoint expects an object.
sourceLocationIdUUIDRequired

ID of the location to transfer from. Must be an active warehouse or truck belonging to the business — a job cannot be used as a source.

quantitydoubleRequired

Quantity to transfer. Must be greater than zero and available at the source location — transfers exceeding the source’s on-hand quantity are rejected.

materialDetailsIdUUIDOptional

The exact inventory record to transfer from, as returned by GET /locations/{id}/materials. Provide either this or materialId.

materialVariationIdUUIDOptional

Narrows materialId to a specific variation. Only valid together with materialId.

materialIdUUIDOptional

Catalog material ID to transfer. Must resolve to exactly one inventory record at the source location — when several exist, narrow with materialVariationId or pass materialDetailsId instead.

reasonstringOptional

Transfer reason recorded on the activity. Accepts one of the default reason keys (CONSUMED, DAMAGED, RESTOCKED, RETURNED, SOLD, STOCKTAKE, STOLEN, DELETED, REPLENISHED, RECONCILED, ADJUSTMENT, OTHER_BUSINESS, WITHOUT_REASON, DEFECTIVE, WARRANTY_REPLACEMENT) or the ID of a custom transfer reason code configured for the business. When omitted, “Without Reason” is recorded.

notesstringOptional

Free-form note recorded on the resulting activity. Maximum 500 characters.

serialNumberslist of stringsOptional

Serial numbers to transfer, when the material is serialized. Each serial must be present at the source location, and each serialized unit becomes its own quantity-1 row on the job. When supplied, the number of serials must equal quantity — supply exactly one serial per unit being transferred. Omit the field entirely to transfer non-serialized stock.

Response

This endpoint returns an object.
datalist of objects

Job rows affected by the transfer. A non-serialized transfer touches a single row; serialized units come back as one row per serial number.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Rate Limit Error