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 (200 OK)

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,
    "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

400 Bad Request

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

Possible reasons for 400 error:

Order ID does not exist
Order is not in a valid state for waybill generation
Missing required documents or information
Order has already been cancelled

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

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

Endpoint​

Description​

Path Parameters​

Request Example​

Success Response (200 OK)​

Error Responses​

400 Bad Request​

401 Unauthorized​

Prerequisites​

What Happens After Waybill Generation​

Important Notes​