Render a Purchase Order document

When to use this endpoint

Use before previewing, downloading or printing an order. It does not send the order to the supplier; orderEmail is the separate delivery action.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use dispatcher CSRF protection when configured. API keys use their owner’s permissions.

Requires explicit View on Purchase Order or Purchase Orders. Non-administrators with legacy Purchase Orders visibility disabled (crm_access bit 256) are denied.

Explicit order IDs must identify active, visible records in the authenticated tenant. TeamAccess follows linked Contracts, Customers, Jobs, Quotes and Departments; legacy department filtering follows Customer, Quote-customer and ordinary customer-Job links. Scoped users cannot read unlinked or Warehouse orders through this check.

Parameters

Parameter	Type	Required	Description
`id`	Positive integer or digit string	Yes	Local Purchase Order ID; not po_num. Missing, malformed or inaccessible IDs fail.
`html`	Integer-compatible flag	No	Default 0: return base64 PDF. Any nonzero integer requests generated HTML and bypasses the PDF cache through the report helper.

Example request

$result = FM_api('PurchaseOrder_getPdf', ['id'=>'1042']);

Example response

{
  "ok": 1,
  "base64": "JVBERi0xLjQK...",
  "filename": "purchase-order"
}

The abbreviated base64 value illustrates the string field; a real response contains the full PDF. With html=1 the payload is {ok:1,html:"...",filename:"..."}.

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error": "permission denied"}`	Page/action rights or the legacy visibility setting deny access.
`{"error": "purchase order does not exist"}`	An explicit parent/header ID is absent, deleted or outside the caller’s scope.
`{"error": "failed to determine purchase order filename"}`	Filename lookup returned no value.
`{"error": "REPORTSERVER_URL not defined"}`	The report helper has no configured report service.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Requires View and an active scoped header. It renders the saved document through the report service using the selected form; report configuration and a usable form are prerequisites.
Rendering does not recalculate or persist totals, clear approval, stamp last_edited or change date_sent. Save/recalculate through the Edit workflow before previewing changed financial data.
PDF mode returns the complete base64 string. HTML mode returns html instead. filename comes from PurchaseOrder_getFilename and the tenant po-filename setting; the fallback is purchase-order without an added extension.
The report service may use/refresh its PDF cache. A nonzero integer html flag requests uncached HTML. Service errors are returned, and can include the resolved filename; filename failures stop rendering.

Side effects

Calls the report service and may refresh its document cache. Purchase Order financial state, approval and sent history remain unchanged; no email is sent.

See it in Fieldmotion

CRM1

In CRM1 Purchase Orders, preview/download an order PDF and filter for PurchaseOrder_getPdf.

CRM2

In CRM2 Purchase Order details or list, preview/download the document and inspect PurchaseOrder_getPdf; html=1 is also supported for HTML consumers.

Related endpoints

PurchaseOrder_orderEmail — Send the order through the mail workflow.
PurchaseOrder_recalculateTotal — Understand the render-time total refresh.