Purchase Order

Purchase Orders represent formal requests issued by a buyer to a supplier, authorising the procurement of specific products at agreed quantities.

The purchase_order Object

Field Name	Type	Description
id	uuid	Primary key for the purchase order.
user_created	object	User who created the record. Read-only.
date_created	datetime	Timestamp in ISO 8601 when the record was created. Read-only.
user_updated	object	User who last updated the record. Read-only.
date_updated	datetime	Timestamp in ISO 8601 when the record was last updated. Read-only.
status	string	Current status of the purchase order. One of: draft, open, partial, completed, cancelled.
purchase_order_number	string	Human-readable purchase order number or reference.
urn	string	Uniform Resource Name uniquely identifying this purchase order, for use in EPCIS messages (typically auto created by system).
purchase_order_date	string	Date the purchase order was issued (ISO 8601 date, e.g. 2024-03-15).
purchase_order_issuer	object	Organisation that issued this purchase order.
supplier	object	Organisation acting as the supplier for this order.
ship_to_location	object	Location to which the ordered goods should be delivered.
line_items	array of objects	Line items detailing the products and quantities ordered.

---

Sub-Objects

User Object (user_created, user_updated)

See Users for the full schema.

Organisation Object (purchase_order_issuer, supplier)

See Organisation for the full schema.

Location Object (ship_to_location)

See Location for the full schema.

Purchase Order Line Item (line_items)

Field	Type	Description
id	uuid	Primary key of the line item.
user_created	object	User who created the line item. Read-only.
date_created	datetime	When the line item was created. Read-only.
user_updated	object	User who last updated the line item. Read-only.
date_updated	datetime	When the line item was last updated. Read-only.
purchase_order_id	uuid	Reference to the parent purchase order.
product	object	Product being ordered. Links to Product.
quantity	number	Quantity of the product ordered.
uom	object	Unit of measurement for the quantity. Links to Unit of Measurement.
unit_price	number	Price per unit of the product.
currency	object	Currency for the unit price.

---

List Purchase Orders

REST

GET /items/purchase_order

GraphQL

query {
  purchase_order {
    id
    status
    purchase_order_number
    purchase_order_date
    purchase_order_issuer {
      id
      organisation_name
    }
    supplier {
      id
      organisation_name
    }
    ship_to_location {
      id
      location_name
    }
    line_items {
      id
      product {
        id
        product_name
      }
      quantity
      unit_price
    }
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit purchase order objects. If no items are available, data will be an empty array.

---

Retrieve a Purchase Order

REST

GET /items/purchase_order/:id

GraphQL

query {
  purchase_order_by_id(id: "purchase_order_id") {
    id
    status
    purchase_order_number
    urn
    purchase_order_date
    purchase_order_issuer {
      id
      organisation_name
    }
    supplier {
      id
      organisation_name
    }
    ship_to_location {
      id
      location_name
    }
    line_items {
      id
      product {
        id
        product_name
      }
      quantity
      uom {
        id
        uom_name
      }
      unit_price
      currency {
        id
      }
    }
  }
}

Returns

Returns a purchase order object if a valid primary key was provided.

---

Create a Purchase Order

REST

POST /items/purchase_order

{
  "purchase_order_number": "PO-2024-001",
  "purchase_order_date": "2024-03-15",
  "status": "issued",
  "purchase_order_issuer": "org-uuid",
  "supplier": "supplier-org-uuid",
  "ship_to_location": "location-uuid"
}

GraphQL

mutation {
  create_purchase_order_item(data: {
    purchase_order_number: "PO-2024-001"
    purchase_order_date: "2024-03-15"
    status: "issued"
    purchase_order_issuer: "org-uuid"
    supplier: "supplier-org-uuid"
    ship_to_location: "location-uuid"
  }) {
    id
    purchase_order_number
    status
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial purchase order object.

Returns

Returns the purchase order object for the created record.

---

Update a Purchase Order

REST

PATCH /items/purchase_order/:id

{
  "status": "received"
}

GraphQL

mutation {
  update_purchase_order_item(id: "purchase_order_id", data: {
    status: "received"
  }) {
    id
    status
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial purchase order object.

Returns

Returns the purchase order object for the updated record.

---

Delete a Purchase Order

REST

DELETE /items/purchase_order/:id

GraphQL

mutation {
  delete_purchase_order_item(id: "purchase_order_id") {
    id
  }
}

Returns

Empty body.