Rating

This API endpoint allows a merchant to request shipping and handling quotes based on a set of order items and a destination zip code.

Methods

rate.quote
rate.services

Entity Properties

Destination
Method Information Properties
Rate Properties
Rate Package Properties

`rate.quote`

rate.quote (object $destination, object $items, object $methodInfo) Request shipping and handling quotes based on a set of order items and a destination zip code.

Parameters

object

Destination (see Destination Properties)

object

Order Items. Format:

[ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]

object

Method Information (see Method Information Properties)

Return Value

An object with rates and handling cost. Each rate lists its estimated packages in packages (see Rate Package Properties).

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "rate.quote",
        [
            {
                "country" : "US",
                "region" : "NY",
                "city" : "New York",
                "street" : "11 Times Square",
                "postcode" : "10036",
                "company" : "Microsoft",
                "classification" : "com"
                
            },
            [
                { 
                    "sku" : "product1", 
                    "qty": 1 
                }, 
                { 
                    "sku" : "product2", 
                    "qty" : 3 
                } 
            ],
            {
                "methods" : "ups_03",
                "signature_required" : "adult",
                "saturday_delivery" : false,
                "overbox" : false
            }
        ]
    ]
}

Example Response

Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "rates" : [
            {
                "code" : "ups_03",
                "description" : "UPS Ground",
                "zone" : "002",
                "days_in_transit" : "2",
                "package_count" : 1,
                "packages" : [
                    {
                        "warehouse_id" : 1,
                        "length" : 12,
                        "width" : 10,
                        "height" : 6,
                        "dimension_unit" : "in",
                        "weight" : 4.25,
                        "weight_unit" : "lb"
                    }
                ],
                "shipping_cost" : "17.23",
                "shipping_cost_currency" : "USD",
                "if_ordered_by" : "15:00:00",
                "min_delivery_date" : "2017-02-05",
                "max_delivery_date" : "2017-02-05",
                "signature_fee" : "1.15",
                "signature_fee_currency" : "USD",
                "multiple_warehouses" : false,
                "allocation" : [
                    { "product1" : [{ "warehouse_id": 1, "qty": "1.000" }] },
                    { "product2" : [{ "warehouse_id": 1, "qty": "3.000" }] }
                ]
            }
        ],
        "handling_cost" : "2.4",
        "handling_cost_currency" : "USD"
    }
}

Package Examples

The following excerpts show only the package_count and packages properties of a single rate, plus related properties where they matter. Two identical packages are listed separately, so the array length matches package_count:

Identical packages

{
    "package_count" : 2,
    "packages" : [
        { "warehouse_id" : 1, "length" : 12, "width" : 10, "height" : 6, "dimension_unit" : "in", "weight" : 4.25, "weight_unit" : "lb" },
        { "warehouse_id" : 1, "length" : 12, "width" : 10, "height" : 6, "dimension_unit" : "in", "weight" : 4.25, "weight_unit" : "lb" }
    ]
}

When the items ship from more than one warehouse, each package has the ID of the warehouse it ships from:

Packages from two warehouses

{
    "package_count" : 2,
    "multiple_warehouses" : true,
    "packages" : [
        { "warehouse_id" : 1, "length" : 12, "width" : 10, "height" : 6, "dimension_unit" : "in", "weight" : 4.25, "weight_unit" : "lb" },
        { "warehouse_id" : 2, "length" : 8, "width" : 6, "height" : 4, "dimension_unit" : "in", "weight" : 1.5, "weight_unit" : "lb" }
    ]
}

The packed-weight estimate remains available when package dimensions are unknown:

Unknown dimensions

{
    "package_count" : 1,
    "packages" : [
        { "warehouse_id" : 1, "length" : null, "width" : null, "height" : null, "dimension_unit" : null, "weight" : 2.75, "weight_unit" : "lb" }
    ]
}

A rate can still succeed when package dimensions are unknown. In that case ShipStream estimates the rate from item data and returns null for the unknown dimensions. When no item or included packaging has a known weight, the package reports null for both weight fields. Known dimensions remain available:

Unknown weight

{
    "package_count" : 1,
    "packages" : [
        { "warehouse_id" : 1, "length" : 16, "width" : 12, "height" : 8, "dimension_unit" : "in", "weight" : null, "weight_unit" : null }
    ]
}

`rate.services`

rate.services (int|null $warehouseId) Get a list of the enabled shipping methods.

Parameters

integer | null

Warehouse. If not specified, the first allowed warehouse will be used.

Return Value

An array of enabled shipping methods.

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "c4d62bb4c368d8158b1221cd5f27a659",
        "rate.services",
        1
    ]
}

Example Response

Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : {
        "external_ltl" : {
            "title" : "LTL",
            "carrier_code" : "external",
            "service" : "ltl",
            "rates_available" : false
        },
        "external_ltl_thirdparty" : {
            "title" : "LTL - Third Party",
            "carrier_code" : "external",
            "service" : "ltl_thirdparty",
            "rates_available" : false
        },
        "fedex_EUROPE_FIRST_INTERNATIONAL_PRIORITY" : {
            "title" : "FedEx Europe First International Priority",
            "carrier_code" : "fedex",
            "service" : "EUROPE_FIRST_INTERNATIONAL_PRIORITY",
            "rates_available" : true
        },
        "fedex_FEDEX_1_DAY_FREIGHT" : {
            "title" : "FedEx 1 Day Freight",
            "carrier_code" : "fedex",
            "service" : "FEDEX_1_DAY_FREIGHT",
            "rates_available" : true
        },
        "fedex_FEDEX_2_DAY" : {
            "title" : "FedEx 2 Day",
            "carrier_code" : "fedex",
            "service" : "FEDEX_2_DAY",
            "rates_available" : true
        },
        "ups_02" : {
            "title" : "UPS 2nd Day Air",
            "carrier_code" : "ups",
            "service" : "02",
            "rates_available" : true
        },
        "ups_03" : {
            "title" : "UPS Ground",
            "carrier_code" : "ups",
            "service" : "03",
            "rates_available" : true
        },
        "ups_07" : {
            "title" : "UPS Worldwide Express",
            "carrier_code" : "ups",
            "service" : "07",
            "rates_available" : true
        }
    }
}

Entity Properties

Destination Properties

Show Destination Properties

string

The “Country” property. ISO-2 format.

string

The “Region” property. 2 characters.

string

The “City” property.

string

The street address. Multi-line street addresses will be separated by a newline (“\n”) character.

string

The “Postal Code” property. Pass as a string to prevent leading 0s from being dropped.

string

The “Company” property.

string

The “Classification” property. Allowed: “res” - residential, “com” - commercial, “po” - post office, “mil” - military, “unk” - unknown.

Method Information Properties

Show Method Information Properties

string

One or more shipping methods. See the Shipping Methods document for a reference.

string

If “adult” then the package(s) will be shipped with the Adult Signature Required option (21 years or older). If “any” then the package(s) will be shipped with the “Direct” signature required (recipient of any age). If “indirect” then the package(s) will be shipped with the “Indirect” signature required (if “Indirect” is not supported by the carrier, this option will fall back to ‘any’). If not specified will default to “none”.

boolean

Saturday delivery option. If not specified will default to ‘false’.

boolean

Request overbox option. If not specified will default to ‘false’.

Rate Properties

Show Rate Properties

string

Shipping methods. See the Shipping Methods document for a reference.

string

See the Shipping Methods document for a reference.

string

Carrier zone.

integer

Days in transit.

integer

The number of packages.

array

The estimated packages for this rate, one entry per package. The array length always equals package_count. See Rate Package Properties.

string

Shipping cost.

string

Shipping cost currency. An ISO 4217 alphabetic code.

string

Same day shipping if you place your order by this time. 24 hour clock time. Eastern Time.

string

Minimum delivery date.

string

Maximum delivery date.

string

Signature fee.

string

Signature fee currency. An ISO 4217 alphabetic code.

boolean

Multiple warehouses flag indicates if the items were split between multiple warehouses.

array

Inventory allocated to warehouses.

string

Base rate, before surcharges are applied.

string

Base rate currency. An ISO 4217 alphabetic code.

string

Residential surcharge.

string

Residential surcharge currency. An ISO 4217 alphabetic code.

string

Area surcharge.

string

Area surcharge currency. An ISO 4217 alphabetic code.

string

Fuel surcharge.

string

Fuel surcharge currency. An ISO 4217 alphabetic code.

string

Weight surcharge.

string

Weight surcharge currency. An ISO 4217 alphabetic code.

string

Packaging surcharge.

string

Packaging surcharge currency. An ISO 4217 alphabetic code.

string

Dimension surcharge.

string

Dimension surcharge currency. An ISO 4217 alphabetic code.

string

Oversize surcharge.

string

Oversize surcharge currency. An ISO 4217 alphabetic code.

string

Demand surcharge.

string

Demand surcharge currency. An ISO 4217 alphabetic code.

string

Additional surcharge.

string

Additional surcharge currency. An ISO 4217 alphabetic code.

Rate Package Properties

Each rate has its own packages. Different shipping methods can pack the same items differently, so compare packages per rate. When a virtual shipping method selects the cheapest or fastest method, the packages come from the method selected at each warehouse. Dimensions describe the packing solution selected for the rate and can be estimates rather than measured boxes. Use each package’s dimension_unit and weight_unit fields to interpret its measurements.

Show Rate Package Properties

integer

The ID of the warehouse the package ships from.

number | null

Package length. null if unknown.

number | null

Package width. null if unknown.

number | null

Package height. null if unknown.

string | null

The unit of measure used for length, width, and height. See: Length Units. null only if all three dimensions are unknown.

number | null

Estimated actual packed weight used for the quote, including packaging weight accounted for by the rating calculation. This differs from dimensional or billable weight. null when no item or included packaging has a known weight; otherwise the reported weight includes known contributions, even if another component’s weight is missing.

string | null

The unit of measure used for weight. See: Weight Units. null when weight is null.

Get Started

Common Features

Shipping

Receiving

Inventory

System

Methods

Entity Properties

`rate.quote`

Parameters

Return Value

Example Request

Example Response

Package Examples

`rate.services`

Parameters

Return Value

Example Request

Example Response

Entity Properties

Destination Properties

Method Information Properties

Rate Properties

Rate Package Properties

​Methods

​Entity Properties

​rate.quote

​Parameters

​Return Value

​Example Request

​Example Response

​Package Examples

​rate.services

​Parameters

​Return Value

​Example Request

​Example Response

​Entity Properties

​Destination Properties

​Method Information Properties

​Rate Properties

​Rate Package Properties

Methods

Entity Properties

`rate.quote`

Parameters

Return Value

Example Request

Example Response

Package Examples

`rate.services`

Parameters

Return Value

Example Request

Example Response

Entity Properties

Destination Properties

Method Information Properties

Rate Properties

Rate Package Properties