Update Purchase Order | Ply | API Documentation

curl -X PUT https://api.getply.com/api/v1/purchase-orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
     -H "API_KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "note": "Updated: deliver to side entrance."
}'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "itemCount": 1,
  "assignedUserIds": [],
  "orderNumber": "PO-1042",
  "status": "DRAFT",
  "type": null,
  "totalCost": 1250,
  "subtotal": 1250,
  "note": "Updated: deliver to side entrance.",
  "supplier": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Acme Supply Co."
  },
  "location": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Main Warehouse"
  },
  "dueDate": "2026-04-15",
  "receivedAt": null,
  "createdAt": "2026-03-20T14:30:00Z",
  "updatedAt": "2026-03-20T15:00:00Z"
}

Updates mutable fields on a purchase order. Only fields included in the request body are modified.

Requires scope: purchase_orders:write

Authentication

API_KEYstring

API Key authentication via header

Path parameters

idUUIDRequired

Purchase order ID.

Request

This endpoint expects an object.

orderNumberstringOptional

Updated order reference number. Maximum 255 characters.

supplierIdUUIDOptional

Updated supplier ID. Pass null to clear.

locationIdUUIDOptional

Updated destination location ID. Pass null to clear.

notestringOptional

Updated note for the supplier. Pass null to clear.

dueDatedateOptional

Updated expected delivery date. Pass null to clear.

Response

This endpoint returns an object.

idUUID

Unique identifier for the purchase order.

itemCountinteger

Number of line items in this purchase order.

assignedUserIdslist of UUIDs

IDs of users assigned to this purchase order.

orderNumberstring

Human-readable order reference number (e.g. PO-1042).

statusenum

Current lifecycle status of the purchase order.

typestring

Optional classification tag for the order (e.g. STANDARD, EMERGENCY).

totalCostdouble

Grand total cost of all items in USD.

subtotaldouble

Subtotal before any adjustments in USD.

notestring

Free-text note for the supplier.

supplierobject

Reference to the supplier for this order.

locationobject

Reference to the destination location.

dueDatedate

ISO 8601 date when the order is expected (e.g. 2026-04-15).

receivedAtdatetime

ISO 8601 timestamp when the order was marked received. null if not yet received.

createdAtdatetime

ISO 8601 timestamp when the record was created.

updatedAtdatetime

ISO 8601 timestamp when the record was last updated.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error