> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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-quote)
* [rate.services](#rate-services)

***

## Entity Properties

* [Destination](#destination-properties)
* [Method Information Properties](#method-information-properties)
* [Rate Properties](#rate-properties)
* [Rate Package 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

**destination** `object`

Destination (see [Destination Properties](#destination-properties))

**items** `object`

Order Items. Format:

```json theme={null}
[ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]
```

**methodInfo** `object`

Method Information (see [Method Information Properties](#method-information-properties))

### Return Value

An object with rates and handling cost. Each rate lists its estimated packages in `packages` (see [Rate Package Properties](#rate-package-properties)).

### Example Request

```json title="Request" theme={null}
{
    "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

```json title="Response" theme={null}
{
    "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`:

```json title="Identical packages" theme={null}
{
    "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:

```json title="Packages from two warehouses" theme={null}
{
    "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:

```json title="Unknown dimensions" theme={null}
{
    "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:

```json title="Unknown weight" theme={null}
{
    "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

**warehouseId** `integer | null`

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

### Return Value

An array of enabled shipping methods.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "c4d62bb4c368d8158b1221cd5f27a659",
        "rate.services",
        1
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "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

**Destination Properties**

**country** `string`

The "Country" property. ISO-2 format.

**region** `string`

The "Region" property. 2 characters.

**city** `string`

The "City" property.

**street** `string`

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

**postcode** `string`

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

**company** `string`

The "Company" property.

**classification** `string`

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

### Method Information Properties

**Method Information Properties**

**methods** `string`

One or more shipping methods. See the [Shipping Methods](https://docs.shipstream.io/merchant-api/shipping-methods.md) document for a reference.

**signature\_required** `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".

**saturday\_delivery** `boolean`

Saturday delivery option. If not specified will default to 'false'.

**overbox** `boolean`

Request overbox option. If not specified will default to 'false'.

### Rate Properties

**Rate Properties**

**code** `string`

Shipping methods. See the [Shipping Methods](https://docs.shipstream.io/merchant-api/shipping-methods.md) document for a reference.

**description** `string`

See the [Shipping Methods](https://docs.shipstream.io/merchant-api/shipping-methods.md) document for a reference.

**zone** `string`

Carrier zone.

**days\_in\_transit** `integer`

Days in transit.

**package\_count** `integer`

The number of packages.

**packages** `array`

The estimated packages for this rate, one entry per package. The array length always equals `package_count`. See [Rate Package Properties](#rate-package-properties).

**shipping\_cost** `string`

Shipping cost.

**shipping\_cost\_currency** `string`

Shipping cost currency. An ISO 4217 alphabetic code.

**if\_ordered\_by** `string`

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

**min\_delivery\_date** `string`

Minimum delivery date.

**max\_delivery\_date** `string`

Maximum delivery date.

**signature\_fee** `string`

Signature fee.

**signature\_fee\_currency** `string`

Signature fee currency. An ISO 4217 alphabetic code.

**multiple\_warehouses** `boolean`

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

**allocation** `array`

Inventory allocated to warehouses.

**base\_rate** `string`

Base rate, before surcharges are applied.

**base\_rate\_currency** `string`

Base rate currency. An ISO 4217 alphabetic code.

**residential\_surcharge** `string`

Residential surcharge.

**residential\_surcharge\_currency** `string`

Residential surcharge currency. An ISO 4217 alphabetic code.

**area\_surcharge** `string`

Area surcharge.

**area\_surcharge\_currency** `string`

Area surcharge currency. An ISO 4217 alphabetic code.

**fuel\_surcharge** `string`

Fuel surcharge.

**fuel\_surcharge\_currency** `string`

Fuel surcharge currency. An ISO 4217 alphabetic code.

**weight\_surcharge** `string`

Weight surcharge.

**weight\_surcharge\_currency** `string`

Weight surcharge currency. An ISO 4217 alphabetic code.

**packaging\_surcharge** `string`

Packaging surcharge.

**packaging\_surcharge\_currency** `string`

Packaging surcharge currency. An ISO 4217 alphabetic code.

**dimension\_surcharge** `string`

Dimension surcharge.

**dimension\_surcharge\_currency** `string`

Dimension surcharge currency. An ISO 4217 alphabetic code.

**oversize\_surcharge** `string`

Oversize surcharge.

**oversize\_surcharge\_currency** `string`

Oversize surcharge currency. An ISO 4217 alphabetic code.

**demand\_surcharge** `string`

Demand surcharge.

**demand\_surcharge\_currency** `string`

Demand surcharge currency. An ISO 4217 alphabetic code.

**additional\_surcharge** `string`

Additional surcharge.

**additional\_surcharge\_currency** `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.

**Rate Package Properties**

**warehouse\_id** `integer`

The ID of the warehouse the package ships from.

**length** `number | null`

Package length. `null` if unknown.

**width** `number | null`

Package width. `null` if unknown.

**height** `number | null`

Package height. `null` if unknown.

**dimension\_unit** `string | null`

The unit of measure used for `length`, `width`, and `height`. See: [Length Units](https://docs.shipstream.io/merchant-api/units-of-measure.md#length). `null` only if all three dimensions are unknown.

**weight** `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.

**weight\_unit** `string | null`

The unit of measure used for `weight`. See: [Weight Units](https://docs.shipstream.io/merchant-api/units-of-measure.md#weight). `null` when weight is `null`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.