Create Waybill

Generate a waybill for an existing order.

Endpoint

POST /orders/{id}/waybills

Description

This will generate a waybill for the specified order. Waybill generation is a separate step after order creation that produces the shipping label and documentation needed for the carrier.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	ID of an existing order

Request Example

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

Success Response (201 Created)

Returns the complete order object with waybill information populated:

{
  "order": {
    "id": 12345,
    "assigned_admin": "admin@example.com",
    "battery_declaration_link": "https://example.com/documents/battery_declaration.pdf",
    "broker_address": null,
    "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": null,
    "importer_of_record_address": null,
    "internal_transaction_number": "TXN987654321",
    "invoice_data": {
      "billable_weights": {
        "metric": {
          "packages": 2,
          "mass_unit": "kg",
          "distance_unit": "cm",
          "volumetric_weight": 50.0,
          "weight": 100.0,
          "billable_weight": 100.0,
          "volume": 0.08
        },
        "imperial": {
          "packages": 2,
          "mass_unit": "lb",
          "distance_unit": "inches",
          "volumetric_weight": 110.23,
          "weight": 220.46,
          "billable_weight": 220.46,
          "volume": 2.83
        }
      },
      "estimate_id": 55788,
      "line_items": [
        {
          "cost": 850.00,
          "currency_id": "USD",
          "description": "Base Shipping Cost"
        },
        {
          "cost": 469.95,
          "currency_id": "USD",
          "description": "Fuel Surcharge"
        }
      ],
      "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": 100.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": null,
    "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": "awaiting_pickup"
      }
    ],
    "shippers_letter_of_instruction_link": "https://example.com/documents/shippers_instruction.pdf",
    "status": "awaiting_pickup",
    "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

422 Unprocessable Entity

Something blocked waybill generation. The error text says what, and the order has usually moved to a waiting status:

{
  "success": false,
  "error": "Commercial invoice required",
  "errors": []
}

`error`	Order moves to	What to do
`Commercial invoice required` (or another missing document)	`awaiting_additional_documentation`	Send the document to your account manager, then call Create Waybill again
`Please settle your Pro Forma invoice before a waybill can be generated`	`awaiting_prepayment`	Settle the pro forma, then call Create Waybill again
`Automatic Waybill generation is not possible at this time, your assigned admin will generate a waybill manually`	`awaiting_waybill_generation`	Nothing; Stream generates the waybill

Carrier-side failures are also returned as 422 with the carrier's message in error.

404 Not Found

The order does not exist or is not visible to your account.

401 Unauthorized

Access token is missing or invalid.

Prerequisites

Before generating a waybill, ensure:

Order exists and is valid - The order must be in a state that allows waybill generation
Address validation - All addresses must be validated and complete
Payment status - Any required prepayments must be completed

What Happens After Waybill Generation

Status Update - Order status typically changes to "awaiting_pickup" or similar
Waybill Number - A unique waybill/tracking number is assigned
Documents Available - Waybill document and shipping labels become available for download via the waybill_document_link field, and the commercial invoice becomes available via the commercial_invoice_link field in the response

Hub Orders

A hub order has two legs and this call readies both. Each leg gets its own waybill, returned in the shipments array in route order (origin → hub first). Read waybill and waybill_document_link per leg from shipments[]; the top-level fields describe a single leg.

Important Notes

Document links in the response are temporary and expire after a short period
The waybill document (accessible via waybill_document_link) contains the shipping label that must be attached to the package
The commercial invoice (accessible via commercial_invoice_link) contains the customs documentation for the shipment
Download both documents immediately after generation as the links expire
A 422 can arrive after the order has already changed status; read the order again to see where it landed

Endpoint​

Description​

Path Parameters​

Request Example​

Success Response (201 Created)​

Error Responses​

422 Unprocessable Entity​

404 Not Found​

401 Unauthorized​

Prerequisites​

What Happens After Waybill Generation​

Hub Orders​

Important Notes​