Purchase orders
Create a blank legacy order line
/a/PurchaseOrderEntry_new
Reserve a blank line ID and display position before the CRM1 editor saves its values.
When to use this endpoint
Use when adding a row in the legacy line editor, then populate the returned ID with PurchaseOrderEntry_save. This creates a real blank row immediately.
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 Edit on either page. Non-administrators with legacy Purchase Orders visibility disabled (crm_access bit 256) are denied.
Explicit line IDs are checked against their active, visible parent orders. A supplied po_id must match the line’s owner. These are tenant-local record IDs, not displayed order numbers.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
po_id | Positive integer or digit string | Yes | Active, visible parent Purchase Order ID. |
stock_type | Integer-compatible | No | Defaults to 2 (miscellaneous) when omitted or integer-converts to 0. Type 1 is catalogue stock. Other nonzero values are rejected; only catalogue type 1 or miscellaneous type 2 is accepted. |
Example request
$result = FM_api('PurchaseOrderEntry_new', ['po_id'=>'1042','stock_type'=>'2']);Example response
{
"ok": 1,
"id": 2081
}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. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Sets parent ID, creation/last-edited timestamps, stock type and the next positive sort number. It does not consume quantity, cost, stock text or totals, and does not populate a stock container.
- A later failed/cancelled editor save does not remove this blank line automatically. Repeating new creates another row; no client idempotency token is used.
- Line creation clears the parent’s approval, including creation of a blank line. Non-administrators with crm_access bit 8192 cannot add lines to approved orders.
- No total recalculation is needed for the inserted blank monetary row. The handler touches the parent and queues PurchaseOrder_edit; it does not add a detailed create-line snapshot audit until a subsequent save.
Side effects
- The line/order mutation uses the tenant-owner lock and a transaction (or caller savepoint). An error rolls back this operation; an earlier, separate API call remains committed. Queued edit-event follow-ups run after the owning commit; saved=1 with a no-replay warning means the data was saved but a follow-up failed.
- Creates the blank row, touches the parent timestamp/cache, resets approval with audit when necessary and fires the edit event after commit.
See it in Fieldmotion
CRM1
In CRM1 Purchase Order details, add a line and inspect PurchaseOrderEntry_new; editing that row subsequently invokes PurchaseOrderEntry_save.
CRM2
CRM2’s spreadsheet replacement uses PurchaseOrderEntry_createData through Layout_setValue. No direct literal Entry_new caller was found in the searched CRM2 page.
Related endpoints
PurchaseOrderEntry_save— Populate the blank line.PurchaseOrderEntry_delete— Remove an unwanted saved row.