Order Statuses

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

Endpoint

GET /order_statuses

Description

Fetch all the different statuses an order may be in throughout its lifecycle. This helps track order progress and understand workflow states.

Request Example

curl -X GET \
  https://orders-api-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": 1,
    "description": "Order Received",
    "value": "order_received"
  },
  {
    "id": 2,
    "description": "Additional Document Required",
    "value": "additional_document_required"
  },
  {
    "id": 3,
    "description": "Awaiting Waybill Generation",
    "value": "awaiting_waybill_generation"
  },
  {
    "id": 4,
    "description": "Awaiting Prepayment",
    "value": "awaiting_prepayment"
  },
  {
    "id": 5,
    "description": "Prepayment Received",
    "value": "prepayment_received"
  },
  {
    "id": 6,
    "description": "Client to Schedule Pickup",
    "value": "client_to_schedule_pickup"
  },
  {
    "id": 7,
    "description": "Admin to Schedule Pickup",
    "value": "admin_to_schedule_pickup"
  },
  {
    "id": 8,
    "description": "System to Schedule Pickup",
    "value": "system_to_schedule_pickup"
  },
  {
    "id": 9,
    "description": "Awaiting Pickup",
    "value": "awaiting_pickup"
  },
  {
    "id": 10,
    "description": "Awaiting Swap Out",
    "value": "awaiting_swap_out"
  },
  {
    "id": 11,
    "description": "Pickup Missed",
    "value": "pickup_missed"
  },
  {
    "id": 12,
    "description": "In Transit",
    "value": "in_transit"
  },
  {
    "id": 13,
    "description": "Partially Delivered",
    "value": "partially_delivered"
  },
  {
    "id": 14,
    "description": "Delivered",
    "value": "delivered"
  },
  {
    "id": 16,
    "description": "Invoice Paid",
    "value": "invoice_paid"
  },
  {
    "id": 17,
    "description": "Incomplete",
    "value": "incomplete"
  },
  {
    "id": 18,
    "description": "Cancelled",
    "value": "cancelled"
  },
  {
    "id": 19,
    "description": "Lost in Transit",
    "value": "lost_in_transit"
  }
]

Response Fields

Field	Type	Description
id	integer	Unique identifier for the status
description	string	Human-readable description of the status
value	string	Machine-readable status value used in API

Order Status Workflow

Initial Processing

• order_received - Order has been created and received by Stream
• additional_document_required - More documentation needed before processing
• awaiting_waybill_generation - Ready for waybill creation
• awaiting_prepayment - Payment required before shipping
• prepayment_received - Payment confirmed, ready to proceed

Pickup Scheduling

• client_to_schedule_pickup - Customer needs to schedule pickup
• admin_to_schedule_pickup - Stream admin will schedule pickup
• system_to_schedule_pickup - System will automatically schedule
• awaiting_pickup - Pickup has been scheduled, waiting for collection
• pickup_missed - Scheduled pickup was missed

Transit and Delivery

• awaiting_swap_out - Package needs to be transferred between carriers
• in_transit - Package is in transit to destination
• partially_delivered - Some items delivered, others pending
• delivered - Package successfully delivered

Post-Delivery

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

Exception States

• incomplete - Order has issues that prevent completion
• cancelled - Order has been cancelled
• lost_in_transit - Package lost during shipping

Usage in API

Filtering Orders by Status

Use the status value when filtering orders:

curl -X GET \
  "https://orders-api-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:

{
  "id": 123,
  "status": "in_transit",
  "reference_number": "Stream0014"
}

Status Change Triggers

Client Actions Required

• additional_document_required: Upload missing documents
• client_to_schedule_pickup: Use pickup scheduling endpoint
• awaiting_prepayment: Process payment through Stream

Stream/System Actions

• admin_to_schedule_pickup: Stream team will handle scheduling
• system_to_schedule_pickup: Automatic scheduling will occur
• awaiting_waybill_generation: Generate waybill via API

Carrier/External Actions

• awaiting_pickup: Waiting for carrier collection
• in_transit: Package with carrier
• delivered: Carrier confirms delivery

Error Responses

401 Unauthorized

Access token is missing or invalid.

Webhook Integration

You can subscribe to order status changes using webhooks:

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

Important Notes

• Status Transitions: Not all status changes are possible - there's a logical workflow progression
• Terminal States: delivered, cancelled, and invoice_paid are typically final states
• Exception Handling: Monitor for incomplete, pickup_missed, and lost_in_transit statuses
• Automation: Some status changes happen automatically, others require action
• Webhooks: Consider using webhooks to get real-time status updates instead of polling

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.