Create a mapped Purchase Order

When to use this endpoint

Use this for a CRM2-style header before creating its lines. Use PurchaseOrder_new for the smaller legacy field set; use createFromJob or createFromRequisitionOrder for those multi-record workflows.

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, plus Add on either page. Non-administrators with legacy Purchase Orders visibility disabled (crm_access bit 256) are denied.

Parameters

Example request

$result = FM_api('PurchaseOrder_createData', [
	'supplier'=>['id'=>'42'],
	'formID'=>'5',
	'reference'=>'PO-2026-1042',
	'deliveryNet'=>'10',
	'deliveryTax'=>'2',
]);

Example response

{
  "ok": 1,
  "id": 1042
}

Errors and unusual responses

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 an available, visible, non-held supplier. The form defaults to 0; a nonzero form must be active and type 5. Targets are validated for their own View permission and record scope; No Link/Warehouse use ID 0 and are unavailable to scoped roles that cannot view such orders.
• Creation stamps the current actor and server creation/edit times. Supplied approval/sent/creation/edit timestamps and a different creator are rejected. The layout-createdBy picker may identify only the current actor.
• The next displayed number is selected under the same tenant-owner lock as insertion. An explicitly supplied poNum must be positive and unused. The returned id is the inserted header ID, not poNum.
• Unknown mapped keys are ignored. The mapper enforces reference length and typed values. Persisted totals are recalculated from line totals plus carriage; an empty header therefore contains carriage only. Layout formulas are not executed by this route.
• Repeated successful calls create separate headers; there is no client idempotency key. A grouped/layout caller can include header and line creation in its owning transaction.

Side effects

• Writes use the tenant-owner lock and a transaction or caller savepoint. A rejected operation rolls back its local writes and checked history. Earlier separate API requests remain committed.
• Edit events, notifications and form follow-ups run after the owning commit. A saved/no-replay warning identifies committed data with a failed follow-up; inspect the saved state rather than repeating creation or sending.
• Inserts the header, writes generic field and checked creation history, recalculates totals and queues the create notification. Direct creation does not add lines, receipts or stock containers.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 uses PurchaseOrder_new and the legacy PurchaseOrderEntry_new/save line editor instead.

CRM2

In CRM2 Purchase Orders, click Create Purchase Order, choose the supplier/form/reference, and inspect Layout_setValue when saving. Its purchaseOrder mapping calls PurchaseOrder_createData internally; a nested call need not appear separately in the browser. The popup uses poDefaultForm when configured, or the only available form, and checks stock/supplier compatibility in the client.

Related endpoints

• PurchaseOrderEntry_createData — Append mapped lines to the new header.
• PurchaseOrder_new — Create the smaller legacy header.