🧮 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.10,
                        "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

• 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