Orders
List Orders
Section titled “List Orders”Returns a list of orders for your account.
/api/v1/ordersQuery Parameters
Section titled “Query Parameters”| Parameter | Type | Default | Description |
|---|---|---|---|
order_status |
string | - | Filter by order status: DRAFT, SENT_FOR_APPROVAL, APPROVED, CONFIRMED, PARTIALLY_RECEIVED, FULLY_RECEIVED |
order_types |
array | [FINISHED_GOOD, RAW_MATERIAL] |
Filter by order types: FINISHED_GOOD, RAW_MATERIAL, PRODUCTION_ORDER |
updated_after |
datetime | - | Orders updated after this timestamp (ISO 8601 format, e.g., 2025-01-15T10:30:00Z) |
date_from |
date | - | Creation date range start (YYYY-MM-DD format, e.g., 2025-01-01) |
date_to |
date | - | Creation date range end (YYYY-MM-DD format, e.g., 2025-01-31) |
supplier_names |
array | - | Filter by supplier names |
Example Request
Section titled “Example Request”curl -X GET "https://api.prediko.io/api/v1/orders?order_status=CONFIRMED" \ -H "Authorization: Bearer YOUR_API_KEY"import requests
response = requests.get( "https://api.prediko.io/api/v1/orders", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"order_status": "CONFIRMED"})orders = response.json()const params = new URLSearchParams({ order_status: "CONFIRMED"});
const response = await fetch( `https://api.prediko.io/api/v1/orders?${params}`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } });const orders = await response.json();Response
Section titled “Response”{ "data": [ { "id": "77de9865-941b-465d-95c0-3614ac2c70dd", "reference": "PO-001", "order_status": "CONFIRMED", "supplier_name": "Acme Corp", "order_type": "FINISHED_GOOD", "origin": "replenish", "quantity_confirmed": 100.0, "quantity_received": 50.0, "delivery_date": ["2025-02-15"], "confirmed_delivery_date": ["2025-02-15"], "initial_delivery_date": ["2025-02-15"], "warehouse_names": ["Main Warehouse"], "cost": 1500.0, "currency": "USD", "created_at": "2025-01-10T14:30:00.000000" } ], "total": 50}Response Fields
Section titled “Response Fields”| Field | Type | Description |
|---|---|---|
data |
array | List of order objects |
total |
integer | Total number of orders matching the query |
Order Object
Section titled “Order Object”| Field | Type | Description |
|---|---|---|
id |
string | Unique order identifier (UUID) |
reference |
string | Order/PO name identifier |
order_status |
string | Current order status |
supplier_name |
string | Name of the supplier |
order_type |
string | Type of order (FINISHED_GOOD, RAW_MATERIAL, PRODUCTION_ORDER) |
origin |
string | Order origin (e.g., “replenish”, “plan”, “NEW”) |
quantity_confirmed |
number | Total quantity confirmed |
quantity_received |
number | Total quantity received so far |
delivery_date |
array | Current expected delivery dates |
confirmed_delivery_date |
array | Confirmed delivery dates |
initial_delivery_date |
array | Initial delivery dates |
warehouse_names |
array | List of warehouse names |
cost |
number | Total order cost |
currency |
string | Currency code |
created_at |
datetime | When the order was created |
Get Order
Section titled “Get Order”Retrieve detailed information about a specific order.
/api/v1/orders/{order_id}Path Parameters
Section titled “Path Parameters”| Parameter | Type | Description |
|---|---|---|
order_id |
string | The unique order identifier |
Query Parameters
Section titled “Query Parameters”| Parameter | Type | Default | Description |
|---|---|---|---|
aggregation_level |
string | SKU |
Aggregation level: SKU (aggregated by SKU), SKU_LOCATION (by SKU and warehouse). When SKU_LOCATION is used, warehouse_name is included in each order part. |
output_format |
string | JSON |
Output format: JSON (standard), EXCEL (spreadsheet-friendly), PDF (PDF document download) |
selected_columns |
array | (defaults) | Columns to include in PDF output. Only used when output_format=PDF. Default columns: product_name, options_export_format, sku_name, barcode, quantity_confirmed, unit_cost_supplier, total_cost |
Example Request
Section titled “Example Request”curl -X GET "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb" \ -H "Authorization: Bearer YOUR_API_KEY"import requests
order_id = "45dcada4-33ef-4331-a6a8-86664986b6fb"response = requests.get( f"https://api.prediko.io/api/v1/orders/{order_id}", headers={"Authorization": "Bearer YOUR_API_KEY"})order = response.json()PDF Export
Section titled “PDF Export”To download a PDF of an order:
# With custom columns (comma-separated)curl -X GET "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb?output_format=PDF&selected_columns=sku_name,quantity_confirmed,total_cost" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o order.pdf
# With default columnscurl -X GET "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb?output_format=PDF" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o order.pdfimport requests
order_id = "45dcada4-33ef-4331-a6a8-86664986b6fb"response = requests.get( f"https://api.prediko.io/api/v1/orders/{order_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={ "output_format": "PDF", "selected_columns": ["sku_name", "quantity_confirmed", "total_cost"] })with open("order.pdf", "wb") as f: f.write(response.content)Response
Section titled “Response”With aggregation_level=SKU (default)
Section titled “With aggregation_level=SKU (default)”{ "id": "77de9865-941b-465d-95c0-3614ac2c70dd", "reference": "13-jan", "order_status": "PARTIALLY_RECEIVED", "supplier_name": "VANS", "order_type": "FINISHED_GOOD", "origin": "replenish", "quantity_confirmed": 15.0, "quantity_received": 6.0, "delivery_date": ["2026-01-18", "2026-01-20"], "confirmed_delivery_date": ["2026-01-15", "2026-01-18", "2026-01-20", "2026-01-25"], "initial_delivery_date": ["2026-01-15", "2026-01-18", "2026-01-20"], "warehouse_names": ["Paris Warehouse", "Paris WH", "Shop location"], "cost": 0.0, "currency": "EUR", "created_at": "2026-01-12T15:03:58.161156", "order_parts": [ { "id": "49b89a4b-f8fc-4b4e-a6c7-b0702d384d4b", "sku_name": "VN-08-white-5", "product_name": "VANS | OLD SKOOL (BUTTERFLY) TRUE WHITE | BLACK", "is_material": false, "supplier_name": "VANS", "supplier_currency": "eur", "options": { "Color": "white", "Size": "5" }, "url": "https://cdn.shopify.com/s/files/1/...", "quantity_confirmed": 10.0, "received": 6.0, "in_transit": 7.0, "confirmed_delivery_date": "2026-01-25", "initial_delivery_date": "2026-01-20", "total_cost": 0.0, "barcode": "NaN", "moq_met": false, "missing_moq": 10, "moq": 300, "moq_type": "PRODUCT", "is_composite": false, "pack_quantity": 1, "pack_type": "SKU", "pack_met": true, "packs_to_order": 10.0, "is_closed": false } ]}With aggregation_level=SKU_LOCATION
Section titled “With aggregation_level=SKU_LOCATION”When using SKU_LOCATION, each order part includes the warehouse_name field:
{ "id": "77de9865-941b-465d-95c0-3614ac2c70dd", "reference": "13-jan", "order_status": "PARTIALLY_RECEIVED", "supplier_name": "VANS", "order_type": "FINISHED_GOOD", "origin": "replenish", "quantity_confirmed": 15.0, "quantity_received": 6.0, "delivery_date": ["2026-01-18", "2026-01-20"], "confirmed_delivery_date": ["2026-01-15", "2026-01-18", "2026-01-20", "2026-01-25"], "initial_delivery_date": ["2026-01-15", "2026-01-18", "2026-01-20"], "warehouse_names": ["Paris Warehouse", "Paris WH", "Shop location"], "cost": 0.0, "currency": "EUR", "created_at": "2026-01-12T15:03:58.161156", "order_parts": [ { "id": "49b89a4b-f8fc-4b4e-a6c7-b0702d384d4b", "sku_name": "VN-08-white-5", "product_name": "VANS | OLD SKOOL (BUTTERFLY) TRUE WHITE | BLACK", "warehouse_name": "Paris Warehouse", "is_material": false, "supplier_name": "VANS", "supplier_currency": "eur", "options": { "Color": "white", "Size": "5" }, "url": "https://cdn.shopify.com/s/files/1/...", "quantity_confirmed": 10.0, "received": 6.0, "in_transit": 7.0, "confirmed_delivery_date": "2026-01-25", "initial_delivery_date": "2026-01-20", "total_cost": 0.0, "barcode": "NaN", "moq_met": false, "missing_moq": 10, "moq": 300, "moq_type": "PRODUCT", "is_composite": false, "pack_quantity": 1, "pack_type": "SKU", "pack_met": true, "packs_to_order": 10.0, "is_closed": false } ]}Order Part Object
Section titled “Order Part Object”| Field | Type | Description |
|---|---|---|
id |
string | Unique part identifier |
sku_name |
string | SKU identifier |
product_name |
string | Product name |
warehouse_name |
string | Warehouse name (only included when aggregation_level=SKU_LOCATION) |
is_material |
boolean | Whether this is a raw material |
supplier_name |
string | Supplier name for this line |
supplier_currency |
string | Supplier’s currency |
options |
object | Product variant options (e.g., Color, Size) |
url |
string | Product image URL |
quantity_confirmed |
number | Confirmed quantity |
received |
number | Quantity received |
in_transit |
number | Quantity in transit |
confirmed_delivery_date |
string | Confirmed delivery date for this line |
initial_delivery_date |
string | Initial delivery date |
total_cost |
number | Total cost for this line |
barcode |
string | Product barcode |
moq_met |
boolean | Whether minimum order quantity is met |
missing_moq |
number | Units missing to meet MOQ |
moq |
number | Minimum order quantity |
moq_type |
string | MOQ type (e.g., PRODUCT, SUPPLIER) |
is_composite |
boolean | Whether this is a composite/bundle product |
pack_quantity |
number | Pack quantity |
pack_type |
string | Pack type (e.g., SKU) |
pack_met |
boolean | Whether pack quantity is met |
packs_to_order |
number | Number of packs to order |
is_closed |
boolean | Whether this line is closed. true when received ≠ quantity_confirmed but no more deliveries are expected |
Error Responses
Section titled “Error Responses”| Status | Description |
|---|---|
| 404 | Order not found |
| 401 | Invalid or missing API key |
Create or Update Orders
Section titled “Create or Update Orders”Create or update purchase orders using UPSERT semantics. Uses purchase_order_name as the unique identifier for idempotent operations.
/api/v1/ordersRequest Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
data |
array | Yes | Array of PO line items (minimum 1) |
date_format |
string | No | Date format for delivery dates. Default: YYYY-MM-DD |
PO Line Item Fields
Section titled “PO Line Item Fields”| Field | Type | Required | Description |
|---|---|---|---|
sku |
string | Yes | Exact SKU identifier |
warehouse |
string | Yes | Warehouse name |
quantity_ordered |
integer | Yes | Total ordered quantity |
quantity_received |
integer | No | Total received so far (cumulative, default: 0) |
supplier |
string | Yes | Supplier name |
purchase_order_name |
string | Yes | Stable PO identifier for updates |
delivery |
string | Yes | Expected delivery date (format depends on date_format) |
status |
string | Yes | DRAFT, APPROVED, CONFIRMED, PARTIALLY_RECEIVED, or FULLY_RECEIVED |
unit_cost |
number | No | Unit cost override, in the supplier’s currency. See Cost Resolution |
extra_cost |
number | No | Extra cost per unit for this line (e.g. freight), in the supplier’s currency. Added to the line’s landed cost |
extra_cost_name |
string | No | Label for extra_cost. Default: Extra cost |
Cost Resolution
Section titled “Cost Resolution”The cost stored on each PO line is resolved in this order:
- The line’s
unit_cost, when provided. - The SKU’s supplier-specific cost for that line’s
supplier. - The SKU’s generic unit cost.
Because supplier-specific costs are applied automatically, you only need to send
unit_cost when you want to override the cost Prediko already holds for that
supplier. Values are interpreted in the supplier’s currency.
Date Formats
Section titled “Date Formats”The date_format parameter accepts:
- JavaScript format:
YYYY-MM-DD,DD/MM/YYYY,MM/DD/YYYY - Python strptime format:
%Y-%m-%d,%d/%m/%Y,%m/%d/%Y
Status Lifecycle
Section titled “Status Lifecycle”- DRAFT: PO drafted, not yet placed with the supplier
- APPROVED: PO approved internally, not yet placed
- CONFIRMED: PO placed with the supplier, nothing received yet
- PARTIALLY_RECEIVED: Some units received
- FULLY_RECEIVED: All units received
Example Request
Section titled “Example Request”curl -X POST "https://api.prediko.io/api/v1/orders" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "sku": "SKU-001", "warehouse": "Main Warehouse", "quantity_ordered": 100, "quantity_received": 0, "supplier": "Acme Corp", "purchase_order_name": "PO-001", "delivery": "2025-02-15", "status": "DRAFT" } ] }'import requests
response = requests.post( "https://api.prediko.io/api/v1/orders", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, json={ "data": [ { "sku": "SKU-001", "warehouse": "Main Warehouse", "quantity_ordered": 100, "quantity_received": 0, "supplier": "Acme Corp", "purchase_order_name": "PO-001", "delivery": "2025-02-15", "status": "DRAFT" } ] })result = response.json()Response
Section titled “Response”On success, the response includes a created_orders array and order_ids list:
{ "errors": [], "created_orders": [ { "order_id": "77de9865-941b-465d-95c0-3614ac2c70dd", "order_name": "PO-001" } ], "order_ids": ["77de9865-941b-465d-95c0-3614ac2c70dd"]}| Field | Type | Description |
|---|---|---|
created_orders |
array | Array of created/updated orders with order_id and order_name |
order_ids |
array | Convenience array of order IDs that were created or updated |
errors |
array | List of errors (empty on full success) |
Example: Recording a Receipt
Section titled “Example: Recording a Receipt”To record units received, send the updated cumulative quantity:
curl -X POST "https://api.prediko.io/api/v1/orders" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "sku": "SKU-001", "warehouse": "Main Warehouse", "quantity_ordered": 100, "quantity_received": 50, "supplier": "Acme Corp", "purchase_order_name": "PO-001", "delivery": "2025-02-15", "status": "PARTIALLY_RECEIVED" } ] }'Update Order Status
Section titled “Update Order Status”Update the status of one or more orders.
/api/v1/orders/statusRequest Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
order_ids |
array | Yes | List of order IDs to update |
order_status |
string | Yes | New status: DRAFT, SENT_FOR_APPROVAL, APPROVED, CONFIRMED, PARTIALLY_RECEIVED, or FULLY_RECEIVED |
Example Request
Section titled “Example Request”curl -X PATCH "https://api.prediko.io/api/v1/orders/status" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "order_ids": ["45dcada4-33ef-4331-a6a8-86664986b6fb", "b2c3d4e5-f6a7-8901-bcde-f12345678901"], "order_status": "CONFIRMED" }'Order Extra Costs
Section titled “Order Extra Costs”Read and write the extra costs on a purchase order: freight, duties, fees and discounts.
Prediko adds them to the goods cost to get the landed cost. All of them are included in
the order’s total_cost. The order’s extra_costs field only counts order-level costs.
Each extra cost applies either to the whole order (e.g. the freight total on a vendor invoice) or to specific lines.
Example: Add Freight from a Vendor Invoice
Section titled “Example: Add Freight from a Vendor Invoice”Your invoice names the PO by its number, which is the order’s reference in Prediko.
- Find the order:
GET /api/v1/ordersand pick the entry whosereferencematches the PO number. Itsidis theorder_idused below. - List its extra costs:
GET /api/v1/orders/{order_id}/extra-costs. - If there is no
Freightcost yet, add one withPOST. If there is one, change its amount withPATCHusing itsid. That way, running your sync twice doesn’t count the freight twice.
import requests
BASE = "https://api.prediko.io/api/v1"HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
orders = requests.get(f"{BASE}/orders", headers=HEADERS).json()["data"]order_id = next(o["id"] for o in orders if o["reference"] == "PO-1042")
costs = requests.get(f"{BASE}/orders/{order_id}/extra-costs", headers=HEADERS).json()freight = next((c for c in costs["extra_costs"] if c["name"] == "Freight"), None)
if freight is None: requests.post( f"{BASE}/orders/{order_id}/extra-costs", headers=HEADERS, json={"name": "Freight", "amount": 412.50}, ).raise_for_status()else: requests.patch( f"{BASE}/orders/{order_id}/extra-costs", headers=HEADERS, json={"extra_costs": [{"id": freight["id"], "amount": 412.50}]}, ).raise_for_status()Order-level costs like this are the simplest choice: they don’t depend on line IDs, and re-sending lines through Create or Update Orders leaves them in place.
List Extra Costs
Section titled “List Extra Costs”/api/v1/orders/{order_id}/extra-costscurl -X GET "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb/extra-costs" \ -H "Authorization: Bearer YOUR_API_KEY"{ "order_id": "45dcada4-33ef-4331-a6a8-86664986b6fb", "extra_costs": [ { "id": "0b6f2c1e-4a8d-4f0e-9a51-2f7d3c8e9b10", "name": "Freight", "amount": 250.0, "is_percentage": false, "is_per_unit": false, "order_part_id": null, "created_at": "2026-10-14T09:00:00", "updated_at": "2026-10-14T09:00:00" } ], "total": 250.0}| Field | Type | Description |
|---|---|---|
extra_costs[].id |
string | Extra cost ID, used to update or delete it |
extra_costs[].name |
string | Label |
extra_costs[].amount |
number | Amount as entered: fixed, percentage, or per unit |
extra_costs[].is_percentage |
boolean | amount is a percentage of the goods cost |
extra_costs[].is_per_unit |
boolean | amount is per unit ordered |
extra_costs[].order_part_id |
string | null | The line the cost applies to, or null for the whole order |
total |
number | Sum of all extra costs, with percentage and per-unit costs worked out |
Add an Extra Cost
Section titled “Add an Extra Cost”/api/v1/orders/{order_id}/extra-costs| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Label, e.g. Freight |
amount |
number | Yes | Fixed amount by default. Use a negative amount for a discount |
is_percentage |
boolean | No | Treat amount as a percentage of the goods cost. Default: false |
is_per_unit |
boolean | No | Treat amount as a cost per unit ordered. Only for a fixed cost with order_part_ids. Default: false |
order_part_ids |
array | No | Lines the cost applies to. Omit for the whole order. Use the order part id values from Get Order with aggregation_level=SKU_LOCATION |
A fixed amount on several lines is split between them in proportion to their quantity. The response lists one ID per extra cost created.
curl -X POST "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb/extra-costs" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Freight", "amount": 250.0}'{ "order_id": "45dcada4-33ef-4331-a6a8-86664986b6fb", "extra_cost_ids": ["0b6f2c1e-4a8d-4f0e-9a51-2f7d3c8e9b10"]}Update Extra Costs
Section titled “Update Extra Costs”Change the name or amount of one or more extra costs. Returns 204 No Content.
/api/v1/orders/{order_id}/extra-costs| Field | Type | Required | Description |
|---|---|---|---|
extra_costs |
array | Yes | Changes to apply |
extra_costs[].id |
string | Yes | Extra cost ID |
extra_costs[].name |
string | No | New label |
extra_costs[].amount |
number | No | New amount |
Each entry needs name, amount or both. To change whether a cost is a percentage,
per unit, or which lines it applies to, delete it and add it again.
curl -X PATCH "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb/extra-costs" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"extra_costs": [{"id": "0b6f2c1e-4a8d-4f0e-9a51-2f7d3c8e9b10", "amount": 275.0}]}'Delete an Extra Cost
Section titled “Delete an Extra Cost”Returns 204 No Content.
/api/v1/orders/{order_id}/extra-costs/{extra_cost_id}curl -X DELETE "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb/extra-costs/0b6f2c1e-4a8d-4f0e-9a51-2f7d3c8e9b10" \ -H "Authorization: Bearer YOUR_API_KEY"Error Responses
Section titled “Error Responses”| Status | Description |
|---|---|
| 404 | An extra cost ID is not on this order |
| 409 | The order has been removed and can no longer be edited |
| 422 | Invalid body, or an order_part_ids entry is not a line on this order |
| 401 | Invalid or missing API key |
Delete Order
Section titled “Delete Order”Delete an order by ID.
/api/v1/orders/{order_id}Path Parameters
Section titled “Path Parameters”| Parameter | Type | Description |
|---|---|---|
order_id |
string | The unique order identifier |
Example Request
Section titled “Example Request”curl -X DELETE "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb" \ -H "Authorization: Bearer YOUR_API_KEY"Response
Section titled “Response”{ "message": "Order '45dcada4-33ef-4331-a6a8-86664986b6fb' deleted successfully"}Error Responses
Section titled “Error Responses”| Status | Description |
|---|---|
| 404 | Order not found |
| 401 | Invalid or missing API key |
