Get Orders

Retrieve orders from the Stream system. You can get all orders or a specific order by ID.

Get All Orders

GET /orders

Description

This will return all orders (20 per page).

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter orders by status
`page`	number	No	Page number (default 1)

Available Order Statuses

order_received
additional_document_required
awaiting_waybill_generation
awaiting_prepayment
prepayment_received
client_to_schedule_pickup
admin_to_schedule_pickup
system_to_schedule_pickup
awaiting_pickup
awaiting_swap_out
pickup_missed
in_transit
partially_delivered
delivered
invoice_paid
incomplete
cancelled
lost_in_transit

Request Example

curl -X GET \
  "https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/orders?status=in_transit&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "orders": [
    {
      "id": 12345,
      "assigned_admin": "admin@example.com",
      "battery_declaration_link": "https://example.com/documents/battery_declaration.pdf",
      "broker_address": {
        "id": 98765,
        "address_1": "456 Broker Avenue",
        "address_2": "Suite 200",
        "address_3": null,
        "city": "Cape Town",
        "classification": "business",
        "company": "Example Broker Co",
        "country": {
          "id": 200,
          "default_postal_code": "0000",
          "dhl_export_code": "ZA",
          "dhl_import_code": "ZA",
          "dhl_tax_code": "ZA",
          "export_code_label": "Export Number",
          "import_code_label": "Import Code",
          "iso_code_2": "ZA",
          "iso_code_3": "ZAF",
          "name": "South Africa",
          "postal_code_required": true,
          "tax_number_label": "VAT Number",
          "taxes_and_duties_config": {
            "id": 150,
            "minimum_value_of_goods": 500.0,
            "minimum_value_of_goods_currency_id": "USD"
          },
          "vat_rate": 0.15
        },
        "country_id": 200,
        "email": "broker@example.com",
        "import_code": "ZA123456789",
        "latitude": -33.9249,
        "longitude": 18.4241,
        "name": "Example Broker",
        "phone": "+27123456789",
        "postal_code": "8001",
        "province": "Western Cape",
        "summary": "South Africa",
        "tax_number": "VAT123456789",
        "time_zone_id": "Africa/Johannesburg"
      },
      "ccd_status": "ccd_not_required",
      "commercial_invoice_link": "https://example.com/documents/commercial_invoice.pdf",
      "company_id": 789,
      "created_at": "2025/08/04 11:48:40 UTC",
      "customer_reference": "CUST-REF-001",
      "customs_clearance_document_link": "https://example.com/documents/customs_clearance.pdf",
      "date_delivered": null,
      "description_of_contents": "Electronic Components",
      "destination_address": {
        "id": 54321,
        "address_1": "789 Destination Street",
        "address_2": "Floor 3",
        "address_3": null,
        "city": "New York",
        "classification": "business",
        "company": "Example Destination Corp",
        "country": {
          "id": 100,
          "default_postal_code": null,
          "dhl_export_code": "US",
          "dhl_import_code": "US",
          "dhl_tax_code": "US",
          "export_code_label": "EIN",
          "import_code_label": "Import Code",
          "iso_code_2": "US",
          "iso_code_3": "USA",
          "name": "United States",
          "postal_code_required": true,
          "tax_number_label": "Tax ID",
          "taxes_and_duties_config": {
            "id": 101,
            "minimum_value_of_goods": 800.0,
            "minimum_value_of_goods_currency_id": "USD"
          },
          "vat_rate": 0.08
        },
        "country_id": 100,
        "email": "destination@example.com",
        "import_code": "US987654321",
        "latitude": 40.7128,
        "longitude": -74.0060,
        "name": "Example Recipient",
        "phone": "+12125551234",
        "postal_code": "10001",
        "province": "New York",
        "summary": "United States",
        "tax_number": "TAX123456789",
        "time_zone_id": "America/New_York"
      },
      "draft_bill_of_lading_link": "https://example.com/documents/draft_bill_of_lading.pdf",
      "eei_eligible": false,
      "eei_request_document_link": "https://example.com/documents/eei_request.pdf",
      "export_permit_link": "https://example.com/documents/export_permit.pdf",
      "final_bill_of_lading_link": "https://example.com/documents/final_bill_of_lading.pdf",
      "importer_of_record_address": {
        "id": 11111,
        "address_1": "321 Importer Road",
        "address_2": "Building C",
        "address_3": "Unit 5",
        "city": "Los Angeles",
        "classification": "business",
        "company": "Example Import Services",
        "country": {
          "id": 100,
          "default_postal_code": null,
          "dhl_export_code": "US",
          "dhl_import_code": "US",
          "dhl_tax_code": "US",
          "export_code_label": "EIN",
          "import_code_label": "Import Code",
          "iso_code_2": "US",
          "iso_code_3": "USA",
          "name": "United States",
          "postal_code_required": true,
          "tax_number_label": "Tax ID",
          "taxes_and_duties_config": {
            "id": 101,
            "minimum_value_of_goods": 800.0,
            "minimum_value_of_goods_currency_id": "USD"
          },
          "vat_rate": 0.08
        },
        "country_id": 100,
        "email": "importer@example.com",
        "import_code": "US555666777",
        "latitude": 34.0522,
        "longitude": -118.2437,
        "name": "Example Importer",
        "phone": "+13105551234",
        "postal_code": "90210",
        "province": "California",
        "summary": "United States",
        "tax_number": "IMP123456789",
        "time_zone_id": "America/Los_Angeles"
      },
      "internal_transaction_number": "TXN987654321",
      "invoice_data": {
        "billable_weights": {
          "metric": {
            "packages": 3,
            "mass_unit": "kg",
            "distance_unit": "cm",
            "volumetric_weight": 15.5,
            "weight": 25.0,
            "billable_weight": 25.0,
            "volume": 0.08
          },
          "imperial": {
            "packages": 3,
            "mass_unit": "lb",
            "distance_unit": "inches",
            "volumetric_weight": 34.17,
            "weight": 55.12,
            "billable_weight": 55.12,
            "volume": 2.83
          }
        },
        "estimate_id": 555888,
        "line_items": [
          {
            "cost": 1250.00,
            "currency_id": "USD",
            "description": "Base Shipping Cost"
          },
          {
            "cost": 187.50,
            "currency_id": "USD",
            "description": "Fuel Surcharge"
          },
          {
            "cost": 95.00,
            "currency_id": "USD",
            "description": "Insurance Fee"
          }
        ],
        "quote_expired": false,
        "shipping_company": "Example Express Shipping",
        "shipping_service": "Priority International"
      },
      "invoice_number": "INV-2024-001",
      "materials_safety_data_sheet_link": "https://example.com/documents/msds.pdf",
      "measured_weight": 25.0,
      "origin_address": {
        "id": 22222,
        "address_1": "123 Origin Boulevard",
        "address_2": "Warehouse A",
        "address_3": null,
        "city": "Johannesburg",
        "classification": "business",
        "company": "Example Origin Company",
        "country": {
          "id": 200,
          "default_postal_code": "0000",
          "dhl_export_code": "ZA",
          "dhl_import_code": "ZA",
          "dhl_tax_code": "ZA",
          "export_code_label": "Export Number",
          "import_code_label": "Import Code",
          "iso_code_2": "ZA",
          "iso_code_3": "ZAF",
          "name": "South Africa",
          "postal_code_required": true,
          "tax_number_label": "VAT Number",
          "taxes_and_duties_config": {
            "id": 150,
            "minimum_value_of_goods": 500.0,
            "minimum_value_of_goods_currency_id": "USD"
          },
          "vat_rate": 0.15
        },
        "country_id": 200,
        "email": "origin@example.com",
        "import_code": null,
        "latitude": -26.2041,
        "longitude": 28.0473,
        "name": "Example Sender",
        "phone": "+27119876543",
        "postal_code": "2000",
        "province": "Gauteng",
        "summary": "South Africa",
        "tax_number": "VAT987654321",
        "time_zone_id": "Africa/Johannesburg"
      },
      "packaging_list_link": "https://example.com/documents/packaging_list.pdf",
      "pickup_date": "2024-03-20",
      "pickup_instructions": "Please call upon arrival",
      "proof_of_delivery_link": "https://example.com/documents/proof_of_delivery.pdf",
      "purpose_of_shipment_id": 8,
      "quote_id": 999888,
      "reference_number": "SHIP-2024-001",
      "scheduled_pickup": "2024-03-20 09:00:00",
      "send_consignee_tracking_details": true,
      "shippers_letter_of_instruction_link": "https://example.com/documents/shippers_instruction.pdf",
      "status": "in_transit",
      "stream_packing_list_link": "https://example.com/documents/stream_packing_list.pdf",
      "tracking_link": "https://example.com/tracking/TRACK123456",
      "value_of_goods": 5000.0,
      "value_of_goods_currency": "USD",
      "waybill": "WB123456789",
      "waybill_document_link": "https://example.com/documents/waybill.pdf"
    }
  ],
  "meta": {
    "page_count": 1,
    "record_count": 1
  }
}

Get Single Order

GET /orders/{id}

Single Order Description

This will return all the details of the specified order.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	ID or reference_number of an existing order

Single Order Request Example

curl -X GET \
  "https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/orders/1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Single Order Success Response (200 OK)

{
  "order": {
    "id": 12345,
    "assigned_admin": "admin@example.com",
    "battery_declaration_link": "https://example.com/documents/battery_declaration.pdf",
    "broker_address": {
      "id": 98765,
      "address_1": "456 Broker Avenue",
      "address_2": "Suite 200",
      "address_3": null,
      "city": "Cape Town",
      "classification": "business",
      "company": "Example Broker Co",
      "country": {
        "id": 200,
        "default_postal_code": "0000",
        "dhl_export_code": "ZA",
        "dhl_import_code": "ZA",
        "dhl_tax_code": "ZA",
        "export_code_label": "Export Number",
        "import_code_label": "Import Code",
        "iso_code_2": "ZA",
        "iso_code_3": "ZAF",
        "name": "South Africa",
        "postal_code_required": true,
        "tax_number_label": "VAT Number",
        "taxes_and_duties_config": {
          "id": 150,
          "minimum_value_of_goods": 500.0,
          "minimum_value_of_goods_currency_id": "USD"
        },
        "vat_rate": 0.15
      },
      "country_id": 200,
      "email": "broker@example.com",
      "import_code": "ZA123456789",
      "latitude": -33.9249,
      "longitude": 18.4241,
      "name": "Example Broker",
      "phone": "+27123456789",
      "postal_code": "8001",
      "province": "Western Cape",
      "summary": "South Africa",
      "tax_number": "VAT123456789",
      "time_zone_id": "Africa/Johannesburg"
    },
    "ccd_status": "ccd_not_required",
    "commercial_invoice_link": "https://example.com/documents/commercial_invoice.pdf",
    "company_id": 789,
    "created_at": "2025/08/04 11:48:40 UTC",
    "customer_reference": "CUST-REF-001",
    "customs_clearance_document_link": "https://example.com/documents/customs_clearance.pdf",
    "date_delivered": null,
    "description_of_contents": "Electronic Components",
    "destination_address": {
      "id": 54321,
      "address_1": "789 Destination Street",
      "address_2": "Floor 3",
      "address_3": null,
      "city": "New York",
      "classification": "business",
      "company": "Example Destination Corp",
      "country": {
        "id": 100,
        "default_postal_code": null,
        "dhl_export_code": "US",
        "dhl_import_code": "US",
        "dhl_tax_code": "US",
        "export_code_label": "EIN",
        "import_code_label": "Import Code",
        "iso_code_2": "US",
        "iso_code_3": "USA",
        "name": "United States",
        "postal_code_required": true,
        "tax_number_label": "Tax ID",
        "taxes_and_duties_config": {
          "id": 101,
          "minimum_value_of_goods": 800.0,
          "minimum_value_of_goods_currency_id": "USD"
        },
        "vat_rate": 0.08
      },
      "country_id": 100,
      "email": "destination@example.com",
      "import_code": "US987654321",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "name": "Example Recipient",
      "phone": "+12125551234",
      "postal_code": "10001",
      "province": "New York",
      "summary": "United States",
      "tax_number": "TAX123456789",
      "time_zone_id": "America/New_York"
    },
    "draft_bill_of_lading_link": "https://example.com/documents/draft_bill_of_lading.pdf",
    "eei_eligible": false,
    "eei_request_document_link": "https://example.com/documents/eei_request.pdf",
    "export_permit_link": "https://example.com/documents/export_permit.pdf",
    "final_bill_of_lading_link": "https://example.com/documents/final_bill_of_lading.pdf",
    "importer_of_record_address": {
      "id": 11111,
      "address_1": "321 Importer Road",
      "address_2": "Building C",
      "address_3": "Unit 5",
      "city": "Los Angeles",
      "classification": "business",
      "company": "Example Import Services",
      "country": {
        "id": 100,
        "default_postal_code": null,
        "dhl_export_code": "US",
        "dhl_import_code": "US",
        "dhl_tax_code": "US",
        "export_code_label": "EIN",
        "import_code_label": "Import Code",
        "iso_code_2": "US",
        "iso_code_3": "USA",
        "name": "United States",
        "postal_code_required": true,
        "tax_number_label": "Tax ID",
        "taxes_and_duties_config": {
          "id": 101,
          "minimum_value_of_goods": 800.0,
          "minimum_value_of_goods_currency_id": "USD"
        },
        "vat_rate": 0.08
      },
      "country_id": 100,
      "email": "importer@example.com",
      "import_code": "US555666777",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "name": "Example Importer",
      "phone": "+13105551234",
      "postal_code": "90210",
      "province": "California",
      "summary": "United States",
      "tax_number": "IMP123456789",
      "time_zone_id": "America/Los_Angeles"
    },
    "internal_transaction_number": "TXN987654321",
    "invoice_data": {
      "billable_weights": {
        "metric": {
          "packages": 3,
          "mass_unit": "kg",
          "distance_unit": "cm",
          "volumetric_weight": 15.5,
          "weight": 25.0,
          "billable_weight": 25.0,
          "volume": 0.08
        },
        "imperial": {
          "packages": 3,
          "mass_unit": "lb",
          "distance_unit": "inches",
          "volumetric_weight": 34.17,
          "weight": 55.12,
          "billable_weight": 55.12,
          "volume": 2.83
        }
      },
      "estimate_id": 555888,
      "line_items": [
        {
          "cost": 1250.00,
          "currency_id": "USD",
          "description": "Base Shipping Cost"
        },
        {
          "cost": 187.50,
          "currency_id": "USD",
          "description": "Fuel Surcharge"
        },
        {
          "cost": 95.00,
          "currency_id": "USD",
          "description": "Insurance Fee"
        }
      ],
      "quote_expired": false,
      "shipping_company": "Example Express Shipping",
      "shipping_service": "Priority International"
    },
    "invoice_number": "INV-2024-001",
    "materials_safety_data_sheet_link": "https://example.com/documents/msds.pdf",
    "measured_weight": 25.0,
    "origin_address": {
      "id": 22222,
      "address_1": "123 Origin Boulevard",
      "address_2": "Warehouse A",
      "address_3": null,
      "city": "Johannesburg",
      "classification": "business",
      "company": "Example Origin Company",
      "country": {
        "id": 200,
        "default_postal_code": "0000",
        "dhl_export_code": "ZA",
        "dhl_import_code": "ZA",
        "dhl_tax_code": "ZA",
        "export_code_label": "Export Number",
        "import_code_label": "Import Code",
        "iso_code_2": "ZA",
        "iso_code_3": "ZAF",
        "name": "South Africa",
        "postal_code_required": true,
        "tax_number_label": "VAT Number",
        "taxes_and_duties_config": {
          "id": 150,
          "minimum_value_of_goods": 500.0,
          "minimum_value_of_goods_currency_id": "USD"
        },
        "vat_rate": 0.15
      },
      "country_id": 200,
      "email": "origin@example.com",
      "import_code": null,
      "latitude": -26.2041,
      "longitude": 28.0473,
      "name": "Example Sender",
      "phone": "+27119876543",
      "postal_code": "2000",
      "province": "Gauteng",
      "summary": "South Africa",
      "tax_number": "VAT987654321",
      "time_zone_id": "Africa/Johannesburg"
    },
    "packaging_list_link": "https://example.com/documents/packaging_list.pdf",
    "pickup_date": "2024-03-20",
    "pickup_instructions": "Please call upon arrival",
    "proof_of_delivery_link": "https://example.com/documents/proof_of_delivery.pdf",
    "purpose_of_shipment_id": 8,
    "quote_id": 999888,
    "reference_number": "SHIP-2024-001",
    "scheduled_pickup": "2024-03-20 09:00:00",
    "send_consignee_tracking_details": true,
    "shippers_letter_of_instruction_link": "https://example.com/documents/shippers_instruction.pdf",
    "status": "in_transit",
    "stream_packing_list_link": "https://example.com/documents/stream_packing_list.pdf",
    "tracking_link": "https://example.com/tracking/TRACK123456",
    "value_of_goods": 5000.0,
    "value_of_goods_currency": "USD",
    "waybill": "WB123456789",
    "waybill_document_link": "https://example.com/documents/waybill.pdf"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid input, object invalid"
}

401 Unauthorized

Access token is missing or invalid.

Important Notes

Document Downloads

All documents for an order are available by performing a GET request to the URL of the document
Document URLs are provided in the order parameters with the _link suffix
All links expire within a short period after the GET request
If you experience a broken document link, repeat the order GET request to get fresh links
Document links do not contain the actual file binary, but rather a link to the actual file

Invoice Data

When the order is finalized and an invoice has been issued, the invoice_data field will be populated
Prior to invoicing, invoice_data will be blank
VAT & Duties will be a line item in the invoice_data when the order is invoiced
The invoice_data.billable_weights field contains both metric and imperial weight measurements
Imperial measurements use "inches" as the distance_unit (not "inch")

Address Structure

All address objects (origin_address, destination_address, importer_of_record_address, broker_address) include detailed country information
Each address contains a nested country object with comprehensive country details including tax rates, postal code requirements, and DHL codes
Address objects include additional fields like latitude, longitude, time_zone_id, and summary

Additional Fields

created_at: Timestamp when the order was created (format: "YYYY/MM/DD HH:MM:SS UTC")
company_id: ID of the company that created the order
value_of_goods and value_of_goods_currency: Value and currency of the shipped goods
pickup_instructions: Special instructions for pickup
scheduled_pickup: Scheduled pickup date and time (format: "YYYY-MM-DD HH:MM:SS")
pickup_date: Scheduled pickup date (format: "YYYY-MM-DD")
date_delivered: Delivery date and time when completed (format: "YYYY/MM/DD HH:MM:SS UTC")
send_consignee_tracking_details: Boolean indicating if tracking details should be sent to consignee
stream_packing_list_link: Link to Stream's packing list document

Date and Time Format

Date and time fields in the API responses use various formats:

created_at: Order creation timestamp (format: "YYYY/MM/DD HH:MM:SS UTC")
pickup_date: Scheduled pickup date (format: "YYYY-MM-DD")
scheduled_pickup: Scheduled pickup date and time (format: "YYYY-MM-DD HH:MM:SS")
date_delivered: Delivery completion timestamp (null if not yet delivered, format: "YYYY/MM/DD HH:MM:SS UTC")### Document Types Available
Commercial invoice
Packaging list
Stream packing list
Waybill document
Customs clearance document
Materials safety data sheet
Battery declaration
Proof of delivery
Draft bill of lading
Final bill of lading
Shipper's letter of instruction
EEI request document
Export permit

Get All Orders​

Description​

Query Parameters​

Available Order Statuses​

Request Example​

Success Response (200 OK)​

Get Single Order​

Single Order Description​

Path Parameters​

Single Order Request Example​

Single Order Success Response (200 OK)​

Error Responses​

400 Bad Request​

401 Unauthorized​

Important Notes​

Document Downloads​

Invoice Data​

Address Structure​

Additional Fields​

Date and Time Format​