Skip to content

Orders

Returns a list of orders for your account.

GET/api/v1/orders
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
Terminal window
curl -X GET "https://api.prediko.io/api/v1/orders?order_status=CONFIRMED" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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
}
Field Type Description
data array List of order objects
total integer Total number of orders matching the query
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

Retrieve detailed information about a specific order.

GET/api/v1/orders/{order_id}
Parameter Type Description
order_id string The unique order identifier
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
Terminal window
curl -X GET "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb" \
-H "Authorization: Bearer YOUR_API_KEY"

To download a PDF of an order:

Terminal window
# 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 columns
curl -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.pdf
{
"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
}
]
}

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
}
]
}
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
Status Description
404 Order not found
401 Invalid or missing API key

Create or update purchase orders using UPSERT semantics. Uses purchase_order_name as the unique identifier for idempotent operations.

POST/api/v1/orders
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
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

The cost stored on each PO line is resolved in this order:

  1. The line’s unit_cost, when provided.
  2. The SKU’s supplier-specific cost for that line’s supplier.
  3. 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.

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
  • 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
Terminal window
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"
}
]
}'

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)

To record units received, send the updated cumulative quantity:

Terminal window
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 the status of one or more orders.

PATCH/api/v1/orders/status
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
Terminal window
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"
}'

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.

  1. Find the order: GET /api/v1/orders and pick the entry whose reference matches the PO number. Its id is the order_id used below.
  2. List its extra costs: GET /api/v1/orders/{order_id}/extra-costs.
  3. If there is no Freight cost yet, add one with POST. If there is one, change its amount with PATCH using its id. 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.

GET/api/v1/orders/{order_id}/extra-costs
Terminal window
curl -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
POST/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.

Terminal window
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"]
}

Change the name or amount of one or more extra costs. Returns 204 No Content.

PATCH/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.

Terminal window
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}]}'

Returns 204 No Content.

DELETE/api/v1/orders/{order_id}/extra-costs/{extra_cost_id}
Terminal window
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"
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 an order by ID.

DELETE/api/v1/orders/{order_id}
Parameter Type Description
order_id string The unique order identifier
Terminal window
curl -X DELETE "https://api.prediko.io/api/v1/orders/45dcada4-33ef-4331-a6a8-86664986b6fb" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"message": "Order '45dcada4-33ef-4331-a6a8-86664986b6fb' deleted successfully"
}
Status Description
404 Order not found
401 Invalid or missing API key