Skip to main content

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​

ParameterTypeRequiredDescription
statusstringNoFilter orders by status
pagenumberNoPage number (default 1)

Available Order Statuses​

  • incomplete
  • order_received
  • awaiting_additional_documentation
  • awaiting_prepayment
  • awaiting_waybill_generation
  • awaiting_schedule_pickup
  • awaiting_pickup
  • awaiting_swap_out
  • pickup_missed
  • in_transit
  • partially_delivered
  • delivered
  • invoice_to_be_paid
  • invoice_paid
  • cancelled
  • lost_in_transit
  • awaiting_consolidation
  • consolidated

See Order Statuses for what each one means.

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,
      "shipments": [
        {
          "shipping_service": "Priority International",
          "waybill": "WB123456789",
          "waybill_document_link": "https://example.com/documents/waybill.pdf",
          "tracking_link": "https://example.com/tracking/TRACK123456",
          "status": "in_transit"
        }
      ],
      "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​

ParameterTypeRequiredDescription
idstringYesID 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,
    "shipments": [
      {
        "shipping_service": "Priority International",
        "waybill": "WB123456789",
        "waybill_document_link": "https://example.com/documents/waybill.pdf",
        "tracking_link": "https://example.com/tracking/TRACK123456",
        "status": "in_transit"
      }
    ],
    "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

Shipments​

  • shipments lists every shipment leg of the order, in route order: the first entry is the leg leaving your origin
  • A direct order has one entry; a hub order has two (origin → hub, then hub → destination)
  • Each entry carries that leg's own shipping_service, waybill, waybill_document_link, tracking_link and status
  • On a hub order the order's top-level waybill, waybill_document_link, tracking_link and status describe a single leg, so read those per leg from shipments[]

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