Industry & Department Solutions

industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Purchase Orders

Purchase Orders API resource representing outbound procurement orders placed with external suppliers, tracking order lines from placement through receipt.

Overview

The Purchase Orders resource represents outbound procurement orders placed with external suppliers. Each record tracks a single order line for a product at a location, capturing the full order lifecycle from placement through to receipt, including quantities, financial value, and current status.

Resource Endpoint

/api/v2/ingest/object/{prefix}PURCHASE_ORDERS{suffix}
/api/v2/ingest/object/{prefix}PURCHASE_ORDERS{suffix}

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) Purchase Orders records via UPSERT operation

Request Headers

Header	Required	Description
`Authorization`	Yes	Your Personal Access Token (PAT) from platform.peak.ai
`Content-Type`	Yes	Must be `application/json`

Properties

Primary Keys

order_number (string) - Unique identifier for the purchase order. Used as the primary key for deduplication and UPSERT operations.

Attributes

Attribute	Data Type	Required	Description
`order_number`	string	Yes	Unique identifier for the purchase order line
`product_id`	string	Yes	Unique identifier for the product being ordered
`location_id`	string	Yes	Unique identifier for the destination location
`source_id`	string	Yes	Identifier of the supplier fulfilling this order
`ordered_at`	timestamp	Yes	Datetime when the order was placed
`order_due_date`	timestamp	Yes	Expected delivery date for the order
`ordered_units`	integer	Yes	Number of units ordered
`receipted_at`	timestamp	No	Datetime when the order was received
`receipted_units`	integer	No	Number of units actually received
`order_line_value`	float	Yes	Total monetary value of the order line
`order_line_status`	string	No	Current status of the order line (for example, "open", "in_transit", "received")

Relationships

Outbound References

The purchase_orders resource does not reference any downstream resources as foreign keys.

Inbound References

The following resources are referenced by purchase_orders:

products — product_id → products.product_id
locations — location_id → locations.location_id

JSON Representation

{
  "solutionName": "INV_OOTB",
  "data": [
    {
      "order_number": "PO-2025-001",
      "product_id": "PROD-001",
      "location_id": "LOC-001",
      "source_id": "SUP-001",
      "ordered_at": "2025-01-10 09:00:00",
      "order_due_date": "2025-01-24 00:00:00",
      "ordered_units": 200,
      "receipted_at": "2025-01-23 14:30:00",
      "receipted_units": 198,
      "order_line_value": 2500.00,
      "order_line_status": "received"
    }
  ],
  "operationType": "UPSERT"
}
{
  "solutionName": "INV_OOTB",
  "data": [
    {
      "order_number": "PO-2025-001",
      "product_id": "PROD-001",
      "location_id": "LOC-001",
      "source_id": "SUP-001",
      "ordered_at": "2025-01-10 09:00:00",
      "order_due_date": "2025-01-24 00:00:00",
      "ordered_units": 200,
      "receipted_at": "2025-01-23 14:30:00",
      "receipted_units": 198,
      "order_line_value": 2500.00,
      "order_line_status": "received"
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/INV_PURCHASE_ORDERS_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "INV_OOTB",
    "data": [
      {
        "order_number": "PO-2025-001",
        "product_id": "PROD-001",
        "location_id": "LOC-001",
        "source_id": "SUP-001",
        "ordered_at": "2025-01-10 09:00:00",
        "order_due_date": "2025-01-24 00:00:00",
        "ordered_units": 200,
        "receipted_at": "2025-01-23 14:30:00",
        "receipted_units": 198,
        "order_line_value": 2500.00,
        "order_line_status": "received"
      }
    ],
    "operationType": "UPSERT"
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/INV_PURCHASE_ORDERS_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "INV_OOTB",
    "data": [
      {
        "order_number": "PO-2025-001",
        "product_id": "PROD-001",
        "location_id": "LOC-001",
        "source_id": "SUP-001",
        "ordered_at": "2025-01-10 09:00:00",
        "order_due_date": "2025-01-24 00:00:00",
        "ordered_units": 200,
        "receipted_at": "2025-01-23 14:30:00",
        "receipted_units": 198,
        "order_line_value": 2500.00,
        "order_line_status": "received"
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

order_number is the primary key, used for deduplication and UPSERT operations.
source_id should correspond to a valid supplier_id in the Suppliers resource.
receipted_at and receipted_units are optional and should be populated once the goods have been physically received.
order_line_value should reflect the total value of the order line in the relevant currency.
All timestamps must be provided in YYYY-MM-DD HH:MM:SS format.
Records are ingested via UPSERT: subsequent updates to the same order_number will overwrite the existing record.

Was this page helpful?

PREVIOUSProducts Parent Child Mapping

NEXTSales

Overview​

Resource Endpoint​

Supported Methods​

Request Headers​

Properties​

Primary Keys​

Attributes​

Relationships​

Outbound References​

Inbound References​

JSON Representation​

Example Request​

Important Notes​

Related Resources​