Create Purchase Order | Ply | API Documentation

curl -X POST https://api.getply.com/api/v1/purchase-orders \
     -H "API_KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "orderNumber": "PO-1042",
  "supplierId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "locationId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "note": "Please ship to back warehouse entrance.",
  "dueDate": "2026-04-15",
  "items": [
    {
      "materialId": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "quantity": 50,
      "price": 25
    }
  ]
}'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "itemCount": 1,
  "assignedUserIds": [],
  "orderNumber": "PO-1042",
  "status": "DRAFT",
  "type": null,
  "totalCost": 1250,
  "subtotal": 1250,
  "note": "Please ship to back warehouse 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-20T14:30:00Z"
}

Creates a new purchase order. Items can be included in the request body or added later via the items endpoints.

Requires scope: purchase_orders:write

Authentication

API_KEYstring

API Key authentication via header

Request

This endpoint expects an object.

orderNumberstringRequired

Order reference number. Required. Maximum 255 characters.

supplierIdUUIDOptional

ID of the supplier for this order.

locationIdUUIDOptional

ID of the destination location.

notestringOptional

Optional free-text note for the supplier.

dueDatedateOptional

Expected delivery date (ISO 8601 date, e.g. 2026-04-15).

itemslist of objectsOptional

Initial line items. Items can also be added after creation.

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