Advanced Rating Features

ShipStation API's Rate Shopping feature has many facets and can provide additonal utility beyond getting the quoted cost for a shipment. This article covers the Retail Rates and Quick Rates features.

Retail Rates

By default, ShipStation API will return the same rate that you'd see if you signed into your carrier account on their website and tried to ship a package. However, there are plenty of use cases where it can be valuable to see the rate available if you were to go to the carrier's retail location and purchase postage. The Retail Rates feature allows those rates to be visible from ShipStation API.

Some things to note:

If ShipStation API does not support retail rates for the carrier you are querying, we will return a 0 amount.
The response object requested_comparison_amount is a sum of the carrier costs for the shipment. It should be compared against the sum of shipping_amount, confirmation_amount and other_amount (insurance_amount will only be a factor if you choose carrier insurance).
This feature is only available at the /v1/rates and /v1/labels endpoints when creating rates or labels with a shipment.

Example Request & Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
POST /v1/rates/ HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
    "shipment": {
        "comparison_rate_type": "retail",
        "ship_to": {
            "name": "The President",
            "phone": "222-333-4444",
            "company_name": "",
            "address_line1": "1600 Pennsylvania Avenue NW",
            "city_locality": "Washington",
            "state_province": "DC",
            "postal_code": "20500",
            "country_code": "US",
            "address_residential_indicator": "no"
        },
        "ship_from": {
            "name": "ShipStation API Team",
            "phone": "222-333-4444",
            "company_name": "ShipStation API",
            "address_line1": "4301 Bull Creek Road",
            "city_locality": "Austin",
            "state_province": "TX",
            "postal_code": "78731",
            "country_code": "US",
            "address_residential_indicator": "no"
        },
        "packages": [
            {
                "package_code": "package",
                "weight": {
                    "value": 6,
                    "unit": "ounce"
                }
            }
        ]
    },
    "rate_options": {
        "carrier_ids": [
            "se-12345"
        ]
    }
}

You can also pass the comparison_rate_type in the shipment when creating a label!

Response

{
    "rate_response": {
        "rates": [
            {
                "rate_id": "se-6384266",
                "rate_type": "shipment",
                "carrier_id": "se-204152",
                "shipping_amount": {
                    "currency": "usd",
                    "amount": 6.7300
                },
                "insurance_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "confirmation_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "other_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "requested_comparison_amount": {
                    "currency": "usd",
                    "amount": 9.3500
                },
                "rate_details": [],
                "zone": 1,
                "package_type": "package",
                "delivery_days": 1,
                "guaranteed_service": false,
                "estimated_delivery_date": "2023-11-02T00:00:00Z",
                "carrier_delivery_days": "1",
                "ship_date": "2023-11-01T00:00:00Z",
                "negotiated_rate": false,
                "service_type": "USPS Priority Mail",
                "service_code": "usps_priority_mail",
                "trackable": true,
                "carrier_code": "usps",
                "carrier_nickname": "My Stamps account",
                "carrier_friendly_name": "USPS",
                "validation_status": "valid",
                "warning_messages": [],
                "error_messages": []
            }
        ],
        "invalid_rates": [],
        "rate_request_id": "se-12345",
        "shipment_id": "se-12345",
        "created_at": "2023-11-01T15:53:03.8069761Z",
        "status": "completed",
        "errors": []
    },
    "shipment_id": "se-12345",
    "carrier_id": null,
    "service_code": null,
    "external_shipment_id": null,
    "shipment_number": null,
    "ship_date": "2023-11-01T00:00:00Z",
    "created_at": "2023-11-01T15:52:52.833Z",
    "modified_at": "2023-11-01T15:52:52.773Z",
    "shipment_status": "pending",
    "ship_to": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "ship_from": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "warehouse_id": null,
    "return_to": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "is_return": false,
    "confirmation": "none",
    "customs": {
        "contents": "merchandise",
        "contents_explanation": null,
        "customs_items": [],
        "non_delivery": "return_to_sender",
        "buyer_shipping_amount_paid": null,
        "duties_paid": null,
        "terms_of_trade_code": null,
        "declaration": null,
        "invoice_additional_details": {
            "freight_charge": null,
            "insurance_charge": null,
            "other_charge": null,
            "other_charge_description": null,
            "discount": null
        },
        "importer_of_record": null
    },
    "external_order_id": null,
    "order_source_code": null,
    "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "delivered_duty_paid": false,
        "non_machinable": false,
        "saturday_delivery": false,
        "dry_ice": false,
        "dry_ice_weight": null,
        "fedex_freight": null,
        "third_party_consignee": false,
        "ancillary_endorsements_option": null,
        "freight_class": null,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null,
        "collect_on_delivery": null,
        "return_pickup_attempts": null,
        "additional_handling": false,
        "own_document_upload": false,
        "limited_quantity": false
    },
    "comparison_rate_type": null,
    "insurance_provider": "none",
    "tags": [],
    "packages": [
        {
            "shipment_package_id": "se-12345",
            "package_id": "se-3",
            "package_code": "package",
            "package_name": "Package",
            "weight": {
                "value": 6.00,
                "unit": "ounce"
            },
            "dimensions": {
                "unit": "inch",
                "length": 0.0,
                "width": 0.0,
                "height": 0.0
            },
            "insured_value": {
                "currency": "usd",
                "amount": 0.00
            },
            "label_messages": {
                "reference1": null,
                "reference2": null,
                "reference3": null
            },
            "external_package_id": null,
            "content_description": null,
            "products": []
        }
    ],
    "total_weight": {
        "value": 6.00,
        "unit": "ounce"
    },
    "items": []}

Quick Rates

We've found that when getting rates just in time to purchase a label, milliseconds matter. That's why we've developed a way to combine the speed of the Rate Estimate endpoint and the detail of the /v1/rates endpoint to offer you a fast and fully-featured way to retrieve rates.

Quick Rates saves time by minimizing the information ShipStation API saves about your request. That means you won't be able to use operations like Create Label from Rate or Retrieve Shipment Rates. You will, however, be able to rate international and multi-package shipments with advanced options. You can even use Quick Rates with Retail Rates!

Example Request & Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
POST /v1/rates/ HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
    "rate_options": {
        "rate_type": "quick",
        "carrier_ids": [
            "se-12345"
        ]
    },
    "shipment": {
        "ship_to": {
            "name": "The President",
            "phone": "222-333-4444",
            "company_name": "",
            "address_line1": "1600 Pennsylvania Avenue NW",
            "city_locality": "Washington",
            "state_province": "DC",
            "postal_code": "20500",
            "country_code": "US",
            "address_residential_indicator": "no"
        },
        "ship_from": {
            "name": "ShipStation API Team",
            "phone": "222-333-4444",
            "company_name": "ShipStation API",
            "address_line1": "4301 Bull Creek Road",
            "city_locality": "Austin",
            "state_province": "TX",
            "postal_code": "78731",
            "country_code": "US",
            "address_residential_indicator": "no"
        },
        "packages": [
            {
                "package_code": "package",
                "weight": {
                    "value": 6,
                    "unit": "ounce"
                }
            }
        ]
    }
}

Response

{
    "rate_response": {
        "rates": [
            {
                "rate_id": null,
                "rate_type": "quick",
                "carrier_id": "se-204152",
                "shipping_amount": {
                    "currency": "usd",
                    "amount": 8.4100
                },
                "insurance_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "confirmation_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "other_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "requested_comparison_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "rate_details": [],
                "zone": 6,
                "package_type": "package",
                "delivery_days": 2,
                "guaranteed_service": false,
                "estimated_delivery_date": "2023-11-03T00:00:00Z",
                "carrier_delivery_days": "2",
                "ship_date": "2023-11-01T00:00:00Z",
                "negotiated_rate": false,
                "service_type": "USPS Priority Mail",
                "service_code": "usps_priority_mail",
                "trackable": true,
                "carrier_code": "usps",
                "carrier_nickname": "My Stamps account",
                "carrier_friendly_name": "USPS",
                "validation_status": "valid",
                "warning_messages": [],
                "error_messages": []
            }
        ],
        "invalid_rates": [],
        "created_at": "2023-11-01T10:38:32.4333382Z",
        "status": "completed",
        "errors": []
    }
}