industry-department-solutions
latest
false
Supply Chain & Retail Solutions API guide
- Overview
- API Resources
Customer Orders API resource representing inbound customer demand, tracking order lines from placement through shipment with quantities and delivery details.
Overview
The Customer Orders resource represents inbound demand from customers, capturing individual order lines placed against a product at a fulfilment location. Each record tracks an order line from initial placement through to shipment, including requested and actual ship dates, quantities, values, and current status. This data is used for demand visibility, service level monitoring, and outbound fulfilment planning.
Resource Endpoint
/api/v2/ingest/object/{prefix}CUSTOMER_ORDERS{suffix}
/api/v2/ingest/object/{prefix}CUSTOMER_ORDERS{suffix}
Supported Methods
| Method | Return Type | Description |
|---|---|---|
| POST | Response | Ingest (create/update) Customer 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_id (string) - Unique identifier for the customer order. Part of the composite primary key.
- order_line_id (string) - Unique identifier for the order line within the order. Part of the composite primary key.
Attributes
| Attribute | Data Type | Required | Description |
|---|---|---|---|
order_id | string | Yes | Unique identifier for the customer order |
order_line_id | string | Yes | Unique identifier for this line within the customer order |
order_date | timestamp | Yes | Datetime when the customer order was placed |
requested_ship_date | timestamp | Yes | Datetime requested by the customer for shipment |
expected_ship_date | timestamp | Yes | Datetime currently expected for shipment |
actual_ship_date | timestamp | No | Actual datetime the order line was shipped |
product_id | string | Yes | Unique identifier for the product ordered |
location_id | string | Yes | Unique identifier for the fulfilment location |
ordered_units | integer | Yes | Number of units ordered by the customer |
ordered_value | float | Yes | Total monetary value of the ordered units |
status | string | No | Current status of the order line (for example, "open", "shipped", "cancelled") |
shipped_units | integer | No | Number of units actually shipped |
shipped_value | float | No | Total monetary value of units actually shipped |
Relationships
Outbound References
The customer_orders resource does not reference any downstream resources as foreign keys.
Inbound References
The following resources are referenced by customer_orders:
- products —
product_id→products.product_id - locations —
location_id→locations.location_id
JSON Representation
{
"solutionName": "INV_OOTB",
"data": [
{
"order_id": "ORD-2025-001",
"order_line_id": "LINE-001",
"order_date": "2025-01-10 09:00:00",
"requested_ship_date": "2025-01-17 00:00:00",
"expected_ship_date": "2025-01-17 00:00:00",
"actual_ship_date": "2025-01-16 14:30:00",
"product_id": "PROD-001",
"location_id": "LOC-001",
"ordered_units": 10,
"ordered_value": 249.90,
"status": "shipped",
"shipped_units": 10,
"shipped_value": 249.90
}
],
"operationType": "UPSERT"
}
{
"solutionName": "INV_OOTB",
"data": [
{
"order_id": "ORD-2025-001",
"order_line_id": "LINE-001",
"order_date": "2025-01-10 09:00:00",
"requested_ship_date": "2025-01-17 00:00:00",
"expected_ship_date": "2025-01-17 00:00:00",
"actual_ship_date": "2025-01-16 14:30:00",
"product_id": "PROD-001",
"location_id": "LOC-001",
"ordered_units": 10,
"ordered_value": 249.90,
"status": "shipped",
"shipped_units": 10,
"shipped_value": 249.90
}
],
"operationType": "UPSERT"
}
Example Request
curl -X POST \
'https://ingestion.peak.ai/api/v2/objects/INV_CUSTOMER_ORDERS_OOTB' \
-H 'Authorization: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"solutionName": "INV_OOTB",
"data": [
{
"order_id": "ORD-2025-001",
"order_line_id": "LINE-001",
"order_date": "2025-01-10 09:00:00",
"requested_ship_date": "2025-01-17 00:00:00",
"expected_ship_date": "2025-01-17 00:00:00",
"actual_ship_date": "2025-01-16 14:30:00",
"product_id": "PROD-001",
"location_id": "LOC-001",
"ordered_units": 10,
"ordered_value": 249.90,
"status": "shipped",
"shipped_units": 10,
"shipped_value": 249.90
}
],
"operationType": "UPSERT"
}'
curl -X POST \
'https://ingestion.peak.ai/api/v2/objects/INV_CUSTOMER_ORDERS_OOTB' \
-H 'Authorization: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"solutionName": "INV_OOTB",
"data": [
{
"order_id": "ORD-2025-001",
"order_line_id": "LINE-001",
"order_date": "2025-01-10 09:00:00",
"requested_ship_date": "2025-01-17 00:00:00",
"expected_ship_date": "2025-01-17 00:00:00",
"actual_ship_date": "2025-01-16 14:30:00",
"product_id": "PROD-001",
"location_id": "LOC-001",
"ordered_units": 10,
"ordered_value": 249.90,
"status": "shipped",
"shipped_units": 10,
"shipped_value": 249.90
}
],
"operationType": "UPSERT"
}'
Important Notes
order_idandorder_line_idtogether form the composite primary key. Both fields must be provided on every record.actual_ship_date,shipped_units, andshipped_valueare optional and should be populated once the order line has been dispatched.ordered_valueandshipped_valueshould reflect monetary totals in the relevant currency.- All timestamps must be provided in
YYYY-MM-DD HH:MM:SSformat. product_idmust correspond to an existing record in the Products resource.location_idmust correspond to an existing record in the Locations resource.- Records are ingested via UPSERT: an existing record with matching primary keys will be updated; otherwise a new record is inserted.