🧮 Rating a Package

Compare real-time shipping rates across multiple carriers

📘 Overview

Use the rate query to get shipping costs for a package.
You can submit multiple rate requests in a single call and receive detailed pricing, estimated delivery, carrier-specific fees, and any errors that occurred during the request.

This is ideal for:

• Showing customers multiple shipping options at checkout
• Pre-calculating shipping costs before label generation
• Testing carrier pricing across accounts and services

🛰️ Query Format

query getRate($request: [RateInput!]!, $services: [CarrierServiceRateInput!]!) {
    rate(request: $request, services: $services) {
        request_id
        rates {
            __typename
            account_number
            carrier
            requested_rate_class
            service_code

            ... on Rate {
                actual_rate_class
                base_price
                total_price
                labelgenius_charge
                estimated_delivery
                guaranteed_delivery
                billing_weight
                disclaimers
                rate_id
                itemized_charges {
                    code
                    charge_amount
                }
                warnings {
                    code
                    message
                }
                carrier_specific
            }

            ... on RateError {
                code
                message
            }
        }
    }
}

✅ Successful Rate Response

When the request is valid, the API returns a list of one or more rate objects under data.rate.rates.

BulkRateResponse

{
    "data": {
        "rate": [
            {
                "request_id": "abc123",
                "rates": [
                    {
                        "__typename": "Rate",
                        "carrier": "UPS",
                        "service_code": "GND",
                        "requested_rate_class": "NEGOTIATED",
                        "actual_rate_class": "NEGOTIATED",
                        "total_price": 8.73,
                        "base_price": 7.91,
                        "labelgenius_charge": 0.1,
                        "estimated_delivery": "2025-06-26",
                        "guaranteed_delivery": null,
                        "account_number": "123456",
                        "rate_id": "rate_abc123",
                        "billing_weight": 1.5,
                        "disclaimers": ["Delivery dates are estimates only."],
                        "carrier_specific": {},
                        "itemized_charges": [
                            {
                                "code": "BASE_CHARGE",
                                "charge_amount": 7.91
                            },
                            {
                                "code": "FUEL_SURCHARGE",
                                "charge_amount": 0.82
                            }
                        ],
                        "warnings": [
                            {
                                "code": "RESIDENTIAL_SURCHARGE",
                                "message": "Delivery address is residential."
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

📦 Required Input

A rate request must contain:

services CarrierServiceRateInput

Use this to specify which carrier and service(s) you'd like to receive rates for.

Fields:

• carrier: Required – one of the supported carrier codes (e.g. UPS, USPS, FedEx, DHL)

• service_code: Required – the specific service you'd like to rate
  Examples include:

  • GND (UPS Ground)
  • USPS_PRIORITY_MAIL (USPS Priority Mail)

• account_number: Optional – your shipper account to use for rating.
  If omitted, the default platform account will be used (if allowed).

• rate_class: Required – defines which type of rate to return (e.g. RETAIL, COMMERCIAL, NEGOTIATED)

🧾 Supported service_code Values

request RateInput

• request_id: String Echoed ID in response to help match client-side requests.

• override_services: CarrierServiceRateInput

  NOTE

  This list overrides the services provided to Query.rate Use it to narrow or customize the rating request for this specific shipment.

• carrier_specific: ShipmentCarrierInput Carrier specific config

• additional: AdditionalInfoInput Additional shipment metadata

• package: PackageRateInput

  • ship_from: AddressInput Origin address

  • ship_to: AddressInput Destination address

  • packaging: Packaging One of:

    • custom_box (requires length, width, height)
    • custom_bag (requires girth, length, width, height)
    • carrier_specific (e.g. USPS Flat Rate or UPS Pak)

  • weight: WeightInput The total shipment weight in imperial or metric

  Optional fields:

  • return_address: AddressInput If different from ship_from
  • extra_services: ExtraService Insurance, signature, Saturday delivery, etc.
  • hazmat: HazmatInfo Lithium batteries, dry ice, etc.
  • customs: CustomsInput Required for international shipments