Skip to navigation

Receive an In-Store Receipt onto a Job

Puts materials bought in store (picked up, not delivered) straight onto a job in one call. Creates a pick-up purchase order linked to the job and receives every line into the job location, the same as choosing the job when receiving in the app. No warehouse stock is created. The order is returned in RECEIVED status, credited to and assigned to the API key’s owner. This call does not finish the job; use the job status endpoint for that.

Each line carries two prices: price is the unit cost you paid, and costForClient is the unit price for the client. Quantities are in each material’s base unit; no unit conversion is applied.

The lines sync to the job in the connected field service app exactly as materials received onto a job in the app do. For Jobber, ServiceTitan and the other field service apps this runs in the background after the receipt is saved, so a sync problem does not fail this call. Housecall Pro is different: the lines are sent to Housecall Pro during this call, so it takes as long as Housecall Pro does, and a Housecall Pro error can fail the call (then nothing is saved in Ply). Retrying such a failure is safe in Ply, but check the Housecall Pro job first in case it kept the lines.

The receipt’s orderNumber is the de-duplication key: importing a number that already exists on a purchase order returns 409 and changes nothing, so a retried request cannot bill the job twice. This also holds after the order is deleted in Ply, until receiving on it is undone. A jobId that is not a job, or a materialVariationId that is not a variation of the line’s material, returns 400. A job, supplier or material that does not exist or belongs to another business returns 404, as does a deleted job or material. Any error creates nothing.

Requires scope: purchase_orders:write

Authentication

API_KEYstring
API Key authentication via header

Request

This endpoint expects an object.
jobIdUUIDRequired
The job the materials were bought for. Must be a job, not a warehouse or truck.
orderNumberstringRequired

The store’s receipt or order number. Used to stop the same receipt being imported twice: if any purchase order that has not been deleted already has this number (ignoring case and surrounding spaces), from any supplier and whether or not it was created as a receipt, the request returns 409, changes nothing, and names the existing purchase order’s id. A deleted purchase order with this number also returns 409 while its items are still received (deleting an order in Ply does not take its items off the job); undo receiving on it in Ply first to import the receipt again. If two stores can issue the same number, prefix it with the store (for example HD-123456). Maximum 255 characters.

itemslist of objectsRequired
Lines on the receipt. At least one, at most 100.
supplierIdUUIDOptional

The store the materials were bought from. Recommended: without it no supplier price history is recorded, and when QuickBooks Online is set to create a bill when a purchase order is received, no bill is created for the receipt.

notestringOptional

Free-text note on the purchase order. Maximum 5000 characters.

Response

This endpoint returns an object.
purchaseOrderobject

The new purchase order, in RECEIVED status. Its location is empty because the order is linked to the job, which is returned in job.

jobobject
The job the receipt was put on.
itemslist of objects
One received line per receipt line, each on the job location.

Errors

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