Create Quote

Create a quote to get shipping estimates from multiple carriers.

Endpoint

POST /quotes

Description

Create a quote on the system, which will then have several estimates associated with it on which an order can be placed. These are called estimates as the final costs will be determined when the underlying provider measures the packages and provides a final official billable weight.

Request Body

Required Fields

Field	Type	Description
`origin_country_id`	integer	ID of the origin country
`destination_country_id`	integer	ID of the destination country
`is_document`	boolean	Whether shipment contains only documents
`is_stackable`	boolean	Whether packages can be stacked
`is_liftgate_required`	boolean	Whether liftgate service is required
`purpose_of_shipment_id`	integer	Purpose of shipment ID (IncoTerms)
`is_shipment_protection_required`	boolean	Whether shipment protection is required
`value_of_goods`	string	Total value of goods being shipped
`value_of_goods_currency_id`	string	Currency code for value of goods
`mass_unit`	string	Unit for weight ("kg" or "lb")
`distance_unit`	string	Unit for dimensions ("cm" or "inch")
`packages`	array	Array of package objects

Optional Fields

Field	Type	Description
`origin_address`	object	Full origin address details
`destination_address`	object	Full destination address details

Package Object Structure

Each package in the packages array must include:

Field	Type	Required	Description
`weight`	number	Yes	Weight of the package
`width`	number	Yes	Width of the package
`height`	number	Yes	Height of the package
`length`	number	Yes	Length of the package

Address Object Structure (Optional)

If providing full addresses for more accurate quotes:

{
  "name": "John Doe",
  "company": "Tech Corp",
  "address_1": "123 Tech Street",
  "address_2": "Suite 100",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postal_code": "2196",
  "country_id": 226,
  "email": "john@techcorp.com",
  "phone": "+27123456789",
  "classification": "business"
}

Request Example

Basic Quote Request (Country to Country)

curl -X POST \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/quotes \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_country_id": 226,
    "destination_country_id": 70,
    "is_document": false,
    "is_stackable": true,
    "is_liftgate_required": false,
    "purpose_of_shipment_id": 8,
    "is_shipment_protection_required": true,
    "value_of_goods": "600.00",
    "value_of_goods_currency_id": "ZAR",
    "mass_unit": "kg",
    "distance_unit": "cm",
    "packages": [
      {
        "weight": 5.5,
        "width": 30.0,
        "height": 20.0,
        "length": 40.0
      },
      {
        "weight": 3.2,
        "width": 25.0,
        "height": 15.0,
        "length": 35.0
      }
    ]
  }'

Detailed Quote Request (With Full Addresses)

curl -X POST \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/quotes \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_address": {
      "name": "John Doe",
      "company": "Tech Corp",
      "address_1": "123 Tech Street",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postal_code": "2196",
      "country_id": 226,
      "email": "john@techcorp.com",
      "phone": "+27123456789",
      "classification": "business"
    },
    "destination_address": {
      "name": "Jane Smith",
      "company": "UK Business",
      "address_1": "456 London Road",
      "city": "London",
      "province": "London",
      "postal_code": "SW1A 2AA",
      "country_id": 70,
      "email": "jane@ukbusiness.com",
      "phone": "+442012345678",
      "classification": "business"
    },
    "is_document": false,
    "is_stackable": true,
    "is_liftgate_required": false,
    "purpose_of_shipment_id": 8,
    "is_shipment_protection_required": true,
    "value_of_goods": "600.00",
    "value_of_goods_currency_id": "ZAR",
    "mass_unit": "kg",
    "distance_unit": "cm",
    "packages": [
      {
        "weight": 5.5,
        "width": 30.0,
        "height": 20.0,
        "length": 40.0
      }
    ]
  }'

Success Response (201 Created)

{
  "id": 1,
  "estimates": [
    {
      "shipping_company": "FedEx USA",
      "shipping_service": "Express Priority",
      "estimate_id": 55788,
      "quote_expired": false,
      "line_items": [
        {
          "description": "Base Rate",
          "cost": 850.00,
          "currency_id": "USD"
        },
        {
          "description": "Fuel Surcharge",
          "cost": 127.50,
          "currency_id": "USD"
        },
        {
          "description": "Shipment Protection Fee",
          "cost": 15.00,
          "currency_id": "USD"
        }
      ],
      "billable_weight": {
        "metric": {
          "packages": 1,
          "mass_unit": "kg",
          "distance_unit": "cm",
          "volumetric_weight": 24.0,
          "weight": 5.5,
          "billable_weight": 24.0
        },
        "imperial": {
          "packages": 1,
          "mass_unit": "lb",
          "distance_unit": "inch",
          "volumetric_weight": 52.91,
          "weight": 12.13,
          "billable_weight": 52.91
        }
      }
    },
    {
      "shipping_company": "DHL Express",
      "shipping_service": "Worldwide Express",
      "estimate_id": 55789,
      "quote_expired": false,
      "line_items": [
        {
          "description": "Base Rate",
          "cost": 920.00,
          "currency_id": "USD"
        },
        {
          "description": "Fuel Surcharge",
          "cost": 138.00,
          "currency_id": "USD"
        }
      ],
      "billable_weight": {
        "metric": {
          "packages": 1,
          "mass_unit": "kg",
          "distance_unit": "cm",
          "volumetric_weight": 24.0,
          "weight": 5.5,
          "billable_weight": 24.0
        },
        "imperial": {
          "packages": 1,
          "mass_unit": "lb",
          "distance_unit": "inch",
          "volumetric_weight": 52.91,
          "weight": 12.13,
          "billable_weight": 52.91
        }
      }
    }
  ]
}

Error Responses

400 Bad Request

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

Common reasons for 400 error:

Missing required fields
Invalid country IDs
Invalid package dimensions or weights
Invalid currency code
Invalid purpose of shipment ID

401 Unauthorized

Access token is missing or invalid.

Understanding the Response

Quote ID

The returned id is the quote identifier that you'll use to retrieve quote details later or reference when creating an order.

Estimates

Each estimate represents a shipping option from a different carrier or service level. Key fields include:

estimate_id: Use this ID when creating an order from this quote
shipping_company: The carrier providing this service
shipping_service: The specific service level
quote_expired: Whether this estimate is still valid
line_items: Breakdown of all costs
billable_weight: How the carrier calculates weight charges

Billable Weight

Carriers use either actual weight or volumetric weight (whichever is higher) to calculate shipping costs. The volumetric weight is calculated based on package dimensions.

Important Notes

Quote Validity: Quotes have expiration times. Check the quote_expired field before creating orders
Final Costs: Quoted prices are estimates. Final costs are determined when the carrier measures and weighs packages
Transit Times: Transit times are estimates based on service provider data and historical shipments
Currency: Most estimates are returned in USD, but this may vary by carrier
Address Impact: Providing full addresses can result in more accurate quotes and pricing
Service Availability: Not all services may be available for all routes or package types

Next Steps

Review Estimates: Compare the different shipping options based on cost, transit time, and service level
Create Order: Use the estimate_id from your chosen estimate to create an order
Quote Retrieval: Use the quote id to retrieve the quote later if needed

Getting Quote Details

You can retrieve the quote details later using:

GET /quotes/{id}

This will return the same quote response with current estimate validity status.

Endpoint​

Description​

Request Body​

Required Fields​

Optional Fields​

Package Object Structure​

Address Object Structure (Optional)​

Request Example​

Basic Quote Request (Country to Country)​

Detailed Quote Request (With Full Addresses)​

Success Response (201 Created)​

Error Responses​

400 Bad Request​

401 Unauthorized​

Understanding the Response​

Quote ID​

Estimates​

Billable Weight​

Important Notes​

Next Steps​

Getting Quote Details​