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
Request
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.
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.
Free-text note on the purchase order. Maximum 5000 characters.
Response
The new purchase order, in RECEIVED status. Its location is empty because the order is linked to the job, which is returned in job.