Order Statuses

Retrieve the list of possible order statuses in the Stream system.

Endpoint

GET /order_statuses

Description

Fetch all the statuses an order may be in throughout its lifecycle. The order's status field on Get Orders uses these values, and so does the status query parameter when filtering.

Request Example

curl -X GET \
  https://orders-production.vatit-stream.com/client_api/v2/order_statuses \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Success Response (200 OK)

[
  { "id": "incomplete", "description": "Incomplete", "value": "incomplete" },
  { "id": "order_received", "description": "Order received", "value": "order_received" },
  { "id": "awaiting_additional_documentation", "description": "Awaiting additional documentation", "value": "awaiting_additional_documentation" },
  { "id": "awaiting_prepayment", "description": "Awaiting prepayment", "value": "awaiting_prepayment" },
  { "id": "awaiting_waybill_generation", "description": "Awaiting waybill generation", "value": "awaiting_waybill_generation" },
  { "id": "awaiting_schedule_pickup", "description": "Awaiting schedule pickup", "value": "awaiting_schedule_pickup" },
  { "id": "awaiting_pickup", "description": "Awaiting pickup", "value": "awaiting_pickup" },
  { "id": "awaiting_swap_out", "description": "Awaiting swap out", "value": "awaiting_swap_out" },
  { "id": "pickup_missed", "description": "Pickup missed", "value": "pickup_missed" },
  { "id": "in_transit", "description": "In transit", "value": "in_transit" },
  { "id": "partially_delivered", "description": "Partially delivered", "value": "partially_delivered" },
  { "id": "delivered", "description": "Delivered", "value": "delivered" },
  { "id": "invoice_to_be_paid", "description": "Invoice to be paid", "value": "invoice_to_be_paid" },
  { "id": "invoice_paid", "description": "Invoice paid", "value": "invoice_paid" },
  { "id": "cancelled", "description": "Cancelled", "value": "cancelled" },
  { "id": "lost_in_transit", "description": "Lost in transit", "value": "lost_in_transit" },
  { "id": "awaiting_consolidation", "description": "Awaiting consolidation", "value": "awaiting_consolidation" },
  { "id": "consolidated", "description": "Consolidated", "value": "consolidated" }
]

Response Fields

Field	Type	Description
id	string	Same as value
description	string	Human-readable description of the status
value	string	Machine-readable status value used in API requests and responses

Order Status Workflow

Before dispatch

• incomplete - Order created but not yet placed
• order_received - Order placed and received by Stream
• awaiting_additional_documentation - Waybill generation was attempted but a required document is missing (for example the commercial invoice)
• awaiting_prepayment - A pro forma invoice must be settled before the waybill can be generated
• awaiting_waybill_generation - Stream is generating the waybill manually
• awaiting_schedule_pickup - Waybill generated, pickup not yet scheduled
• awaiting_pickup - Pickup scheduled, waiting for the carrier to collect
• awaiting_swap_out - Package needs to be transferred between carriers
• pickup_missed - The carrier did not collect during the scheduled window

Transit and delivery

• in_transit - Package is with the carrier
• partially_delivered - Some packages delivered, others pending
• delivered - Package successfully delivered

Billing

• invoice_to_be_paid - Final invoice issued, payment pending
• invoice_paid - All payments completed

Exceptions

• cancelled - Order has been cancelled (see Cancel Order)
• lost_in_transit - Package lost during shipping

Consolidation

• awaiting_consolidation - Shipment is parked at a hub waiting to be consolidated with others
• consolidated - Shipment has been consolidated into another shipment

What each status asks of you

Status	Action
awaiting_additional_documentation	Send the missing document to your account manager, then call Create Waybill again
awaiting_prepayment	Settle the pro forma invoice, then call Create Waybill again
awaiting_schedule_pickup	Call Schedule Pickup
pickup_missed	Schedule a new pickup
awaiting_waybill_generation	None; Stream generates the waybill and the order moves on

Usage in API

Filtering Orders by Status

Use the status value when filtering orders:

curl -X GET \
  "https://orders-production.vatit-stream.com/client_api/v2/orders?status=in_transit" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Order Status in Responses

Order objects include the current status. On a hub order each leg has its own status inside shipments[]:

{
  "id": 123,
  "status": "in_transit",
  "reference_number": "Stream0014",
  "shipments": [
    { "status": "in_transit", "waybill": "WB-ORIGIN-TO-HUB" },
    { "status": "order_received", "waybill": null }
  ]
}

Webhook Integration

Subscribe to status changes with Register Webhook. The shipment.updated.status event fires for order_received, in_transit and delivered only; poll for the others.

{
  "webhook": {
    "target_url": "https://your-app.com/webhooks/orders",
    "events": ["shipment.updated.status"]
  }
}

Important Notes

• Status Transitions: Not all status changes are possible - there's a logical workflow progression
• Terminal States: delivered, cancelled, invoice_paid and consolidated are final states
• Exception Handling: Monitor for awaiting_additional_documentation, awaiting_prepayment, pickup_missed and lost_in_transit

Caching Recommendations

Order status data is stable and can be cached for extended periods. This reference data rarely changes, so daily or weekly cache refresh is sufficient.