FAfactorialhr
Procurement > PurchaseOrder

Creates a Purchase order

Changed on

Create a standalone purchase order (e.g. pushed by an ERP integrator), not linked to any purchase request. The purchase order is pinned to the company's ACTIVE purchase order template version; template fields are addressed by their stable field_key and validated against that version: unknown field keys, missing required fields and reference values that do not resolve in the company are all rejected with a field-keyed 422. A vendor_id or legal_entity_id that does not exist or is not visible to the credential is rejected earlier by the platform resource check (400).

post/api/2026-10-01/resources/procurement/purchase_orders

Request

  • Base URL
    https://api.factorialhr.com
  • URL
    https://api.factorialhr.com/api/2026-10-01/resources/procurement/purchase_orders
  • Auth
    API key in header x-api-key

Request body

company_idstring required

Company identifier, refers to /api/me endpoint.

legal_entity_idstring required

Identifier of the legal entity that owns the purchase order. Must belong to the company.

vendor_idstring

Identifier of the vendor (Finance contact) by internal Factorial id. Vendors synced from an external system must be resolved to their Factorial id first (e.g. via the vendors read endpoint).

currencystring required

Currency code in ISO 4217 format.

datestring

Purchase order date. Defaults to today when omitted.

deadlinestring

Deadline date for the purchase order delivery or completion.

status'draft' | 'pending' | 'ordered' | 'partial' | 'received' | 'closed'

Status of the purchase order. Defaults to draft. processing is an internal transient status and is rejected.

descriptionstring

Description or notes about the purchase order.

preferred_payment_method'banktransfer' | 'cash' | 'virtualcard'

Preferred payment method for this purchase order.

Example request

{
  "company_id": "1",
  "legal_entity_id": "3456",
  "vendor_id": "9012",
  "currency": "EUR",
  "date": "2025-01-15",
  "deadline": "2025-02-15",
  "status": "draft",
  "description": "Office supplies for Q1 2025",
  "preferred_payment_method": "banktransfer",
  "header_field_values": [
    {
      "field_key": "cost_center",
      "value": "42"
    },
    {
      "field_key": "notes",
      "value": "Rack servers for the Berlin DC"
    }
  ],
  "line_items": [
    {
      "position": 0,
      "fields": [
        {
          "field_key": "concept",
          "value": "Rack server"
        },
        {
          "field_key": "quantity",
          "value": "2"
        },
        {
          "field_key": "unit_price",
          "value": "150000"
        }
      ]
    }
  ]
}

Response

CREATED

idstring required

Unique identifier of the purchase order

po_numberinteger required

Purchase order number assigned to this order

descriptionstring required

Description or notes about the purchase order

status'processing' | 'draft' | 'pending' | 'ordered' | 'partial' | 'received' | 'closed' required

Current status of the purchase order

datestring required

Date when the purchase order was created

deadlinestring

Deadline date for the purchase order delivery or completion. Writable through the update endpoint (omitted or null keeps it); readable here so the GET -> modify -> PUT roundtrip is complete.

vendor_idstring

Identifier of the vendor (contact) associated with this purchase order

purchase_request_idstring

Identifier of the purchase request that generated this purchase order, if any. Externally-created purchase orders (e.g. synced from an ERP) have no purchase request.

legal_entity_idstring required

Identifier of the legal entity that owns this purchase order

company_idstring required

Identifier of the company that owns this purchase order

formatted_po_numberstring required

Formatted purchase order number with prefix (e.g., PO-00001)

preferred_payment_method'banktransfer' | 'cash' | 'virtualcard'

Preferred payment method for this purchase order

po_template_version_idstring

Identifier of the pinned PO template version this purchase order uses. Fetch that version (and its field definitions) to interpret the purchase order's header and line-item field keys. Null for legacy purchase orders created without a template.

Example response

{
  "id": "678432",
  "po_number": 2131,
  "description": "Office supplies for Q1 2025",
  "status": "pending",
  "cost": {
    "cents": 10000,
    "currency": "EUR"
  },
  "date": "2025-01-15",
  "deadline": "2025-02-15",
  "vendor_id": "9012",
  "purchase_request_id": "5678",
  "legal_entity_id": "3456",
  "company_id": "1",
  "formatted_po_number": "PO-02131",
  "preferred_payment_method": "banktransfer",
  "po_template_version_id": "1",
  "header_field_values_by_key": [
    {
      "field_key": "delivery_notes",
      "value": "Leave at reception"
    }
  ],
  "line_items_by_key": [
    {
      "id": 51,
      "position": 0,
      "fields": [
        {
          "field_key": "quantity",
          "value": "10"
        }
      ]
    }
  ]
}

Changes