PurchaseOrders

Creates a purchase order in `Draft`, optionally with its lines.

Requires ManagePurchaseOrders and an Idempotency-Key header. Same as "New Purchase Order" in the app: the vendor must be active in your organization (or omit vendorId and name a one-off vendor), the receiving location must be an active top-level location that is not a job site, and each line names one of your items or bundles. The order and its lines are written together or not at all. A new order is a Draft: move it along with /mark-ordered, /mark-shipped and /mark-delivered, then /receive it. Attributed to the key's creator. Example: { "vendorId": 7, "receivingLocationId": 1, "lines": [ { "itemId": 12, "quantityOrdered": 24, "unitPrice": 3.10 } ] }.

post/api/v1/purchase-orders

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/purchase-orders
  • Auth: HTTP bearer

Request body

orderNumberstring nullable

PO number, up to 50 characters. Omit to have one generated the way the app does: {vendor name, letters and digits}-{yyyy-MM-dd}-{nnnn} (e.g. AcmeSupply-2026-09-22-0001), or PO-{yyyy}-{nnnn} without a vendor.

externalOrderNumberstring nullable

The vendor's own order or confirmation number, up to 50 characters. Example: SO-88213.

vendorIdinteger nullable

An active vendor from GET /api/v1/vendors. Omit for a one-off vendor named in vendorName. Example: 7.

vendorNamestring nullable

Vendor name on the order, up to 200 characters. Defaults to the vendor record's name when vendorId is given.

vendorContactEmailstring nullable

Contact email for this order, up to 100 characters. Defaults to the vendor record's contact email.

vendorContactPhonestring nullable

Contact phone for this order, up to 20 characters. Defaults to the vendor record's contact phone.

orderDatestring date-time nullable

Order date (organization-local calendar date, no offset). Defaults to today. Example: 2026-09-22.

expectedDeliveryDatestring date-time nullable

Expected delivery date (organization-local calendar date, no offset); optional. Example: 2026-09-30.

totalCostnumber double nullable

Order total as agreed with the vendor, in currency; optional. Example: 74.40.

currencystring nullable

ISO 4217 currency code, 3 letters. Defaults to USD.

receivingLocationIdinteger

Where the order will be received: an active, top-level location that is not a job site (see GET /api/v1/locations?parentLocationId=0). Example: 1.

notesstring nullable

Free-text notes on the order.

Response

Created; Location points at the order, body as GET /api/v1/purchase-orders/{id}.

idinteger

Numeric id used in /api/v1/purchase-orders/{id}. Unique within this organization. Example: 412.

syncIdstring uuid

Stable cross-device identifier (GUID) — also the pagination cursor value. Example: 3c9d1a2b-7e4f-4b6a-8c1d-5e6f7a8b9c0d.

orderNumberstring

The organization's purchase-order number. Example: PO-ACME-20260915-01.

externalOrderNumberstring nullable

The vendor's own order or confirmation number; null when not recorded. Example: SO-88213.

statusstring

Order status name, derived by the app from the order's shipments and received quantities. One of Draft (no shipment yet), Ordered, Shipped, PartialShipped, Delivered (at the receiving location, nothing received yet), PartialReceived, Received (every unit received and every shipment delivered), Cancelled.

vendorIdinteger nullable

Id of the vendor record; null for a one-off vendor typed on the order.

vendorNamestring nullable

Vendor name (the vendor record's name, else the one-off name on the order). Example: Acme Supply. Null when neither is set.

orderDatestring date-time

Order date as entered in the app: the organization's local calendar date, yyyy-MM-ddT00:00:00 with no UTC offset (the date-time format here is a local date, not an RFC 3339 instant; do not convert it between time zones). Example: 2026-09-15T00:00:00.

expectedDeliveryDatestring date-time nullable

Expected delivery date as entered in the app, same local calendar-date format as orderDate (no UTC offset). Example: 2026-09-22T00:00:00. Null when unknown.

receivedDatestring date-time nullable

When the order became fully Received, ISO-8601 UTC; null until then.

totalCostnumber double nullable

Order total in currency as recorded on the order; null when not calculated. Example: 1249.50.

currencystring

ISO-4217 currency code of the prices on the order. Example: USD.

receivingLocationIdinteger

Id of the location stock is received at by default (see /api/v1/locations). Example: 10.

receivingLocationNamestring nullable

Name of receivingLocationId. Example: Main Warehouse.

lineCountinteger

Number of lines on the order. Example: 3.

quantityOrderedinteger

Units ordered across all lines. Example: 40.

quantityReceivedinteger

Units received across all lines. Example: 25.

createdAtstring date-time

Creation time, ISO-8601 UTC. Example: 2026-09-15T14:05:00Z.

updatedAtstring date-time nullable

Last modification time (including a receipt), ISO-8601 UTC; null when never modified since creation.

notesstring nullable

Free-text notes on the order. Example: Deliver to dock 3. Null when none.

Changes

No recorded changes to this operation across all 1 revision of this API.