Skip to main content

PurchaseOrder

A procurement transaction requesting goods from a vendor.

orderNumberstring

Human-readable PO number displayed in Keychain OS and sent to the vendor.

Example: PO-2025-0471
vendorIdstring

Reference to the vendor this PO is placed with.

vendorNamestring

Display name of the vendor.

Example: Pacific Ingredients Co.
invoiceDatestring<date>

Date the PO was invoiced (ISO 8601).

Example: 2025-03-10
expectedDeliveryDatestring<date>

Expected delivery date. May be updated by the vendor during the review process.

Example: 2025-03-17
statusstring

Current status of the purchase order:

  • draft — created but not yet sent to the vendor.
  • sent — transmitted to the vendor for review.
  • accepted — vendor has confirmed the order.
  • shipped — goods are in transit.
  • partially_received — some line items have been received, others are still outstanding.
  • completed — all line items fully received.
  • cancelled — order was cancelled.
  • delayed — delivery is past the expected date.

Possible values: [draft, sent, accepted, shipped, partially_received, completed, cancelled, delayed]

Example: completed
subtotalnumber

Sum of all line item totals before tax, discounts, and shipping.

Example: 2800
taxAmountnumber

Total tax applied to the order.

Example: 224
discountnumber

Total discount applied to the order. A value of 0 means no discount.

Example: 0
shippingCostnumber

Shipping charges for the order.

Example: 150
totalAmountnumber

Final amount due (subtotal + tax - discount + shipping).

Example: 3174
currencystring

Three-letter currency code (ISO 4217).

Example: USD
paymentTermsstring

Payment terms for this PO (e.g., "Net 30", "Due on receipt"). Defaults from the vendor record unless overridden.

Example: Net 30
lineItems object[]

The items ordered on this PO, with quantities, pricing, and receiving status.

  • Array [
    • itemIdstring

    Reference to the item being ordered.

    Example: 2087
    itemNamestring

    Display name of the item.

    Example: Organic Tahini
    descriptionstring

    Optional free-text description for this line (e.g., special instructions to the vendor).

    quantitynumber

    Quantity ordered.

    Example: 200
    unitstring

    Unit of measure.

    Example: lbs
    unitPricenumber

    Price per unit.

    Example: 3.25
    totalPricenumber

    Line total (quantity x unit price), before tax.

    Example: 650
    taxRatenumber

    Tax rate applied to this line item, expressed as a decimal (e.g., 0.08 for 8%).

    Example: 0.08
    receivedQuantitynumber

    Quantity received so far. Updated each time an intake is recorded against this PO line.

    Example: 200
    lineStatusstring

    Fulfillment status of this line item:

    • pending — no goods received yet.
    • partially_received — some quantity received, but less than ordered.
    • fully_received — the full ordered quantity has been delivered.

    Possible values: [pending, partially_received, fully_received]

    Example: fully_received
  • ]
    • PurchaseOrder
    {
      "orderNumber": "PO-2025-0471",
      "vendorId": "string",
      "vendorName": "Pacific Ingredients Co.",
      "invoiceDate": "2025-03-10",
      "expectedDeliveryDate": "2025-03-17",
      "status": "completed",
      "subtotal": 2800,
      "taxAmount": 224,
      "discount": 0,
      "shippingCost": 150,
      "totalAmount": 3174,
      "currency": "USD",
      "paymentTerms": "Net 30",
      "lineItems": [
        {
          "itemId": "2087",
          "itemName": "Organic Tahini",
          "description": "string",
          "quantity": 200,
          "unit": "lbs",
          "unitPrice": 3.25,
          "totalPrice": 650,
          "taxRate": 0.08,
          "receivedQuantity": 200,
          "lineStatus": "fully_received"
        }
      ]
    }